RD_AddCart
7
October 2015
Rivendell C Library Manual

# rd_addcart

Rivendell Add Cart C Library Function
Todd
Baker
bakert@rfa.org
Rivendell C Library Author

        #include <rivwebcapi/rd_addcart.h>

        int RD_AddCart
           struct rd_cart * cart[]
          const char hostname[]
          const char username[]
          const char passwd[]
          const char ticket[]
          const char group[]
          const char type[]
          const unsigned cartnumber
          const char user_agent[]
          unsigned * numrecs

## Description

`RD_AddCart` is the function to use to add a cart to an existing Rivendell Database.

This function adds the cart number to the Rivendell database on hostname. Default values are used when the cart is created.

### RD_AddCart function call fields

FIELD NAME | FIELD TYPE | MEANING | REMARKS
--- | --- | --- | ---
*rd_cart | Pointer to rd_cart structure | Memory location to store cart information | Mandatory
hostname | Character Array | Name Of Rivendell DB Host | Mandatory
username | Character Array | Rivendell User Name | Mandatory When NO Ticket Provided.
passwd | Character Array | Rivendell User Password | Mandatory When NO Ticket Provided.
ticket | Character Array | Rivendell Authentification Ticket | Mandatory When NO User/Password Pair Provided.
group | Character Array | Rivendell Group Name | Mandatory
type | Character Array | Cart Type | Mandatory
cartnumber | unsigned integer | Cart Number | Mandatory
user_agent | Character Array | User Agent Value put into HTTP request | Optional (default is Rivendell-C-API/x.x.x)
*numrecs | pointer to integer | memory location for number of records returned | Mandatory

When successful function will return the number of records sent (numrecs) and a rd_cart structure which is stored in the provided memory locations. The rd_cart structure has the following fields:

        struct rd_cart {
      	  unsigned cart_number;                /* Cart Number */
      	  unsigned cart_type;                  /* Cart Type */
      	  char cart_grp_name[41];              /* Group Name */
      	  char cart_title[1021];                /* Cart Title */
      	  char cart_artist[1021];               /* Artist */
      	  char cart_album[1021];                /* Album */
      	  int cart_year;                       /* Year */
      	  char cart_label[257];                 /* Label */
      	  char cart_client[257];                /* Client */
      	  char cart_agency[257];                /* Agency */
      	  char cart_publisher[257];             /* Publisher */
      	  char cart_composer[257];              /* Composer */
      	  char cart_user_defined[1021];         /* User Defined */
      	  int  cart_usage_code;                /* Usage Code */
      	  int cart_forced_length;              /* Forced Length */
      	  int cart_average_length;             /* AverageLength */
      	  int cart_length_deviation;           /* Length Deviation */
      	  int cart_average_segue_length;       /* Average Segue Length */
      	  int cart_average_hook_length;        /* Average Hook Length */
      	  unsigned  cart_cut_quantity;         /* Cut Quantity */
      	  unsigned  cart_last_cut_played;      /* Last Cut Played */
      	  unsigned  cart_validity;             /* Validity */
      	  int cart_enforce_length;             /* Enforce Length Flag */
      	  int cart_asyncronous;                /* Asyncronous Flag */
      	  char cart_owner[257];                 /* Owner */
      	  struct tm cart_metadata_datetime;    /* Metadata Datetime */
      	  char cart_notes[4098];               /* Notes */
        };

          All character arrays above are the sizes listed and are null-terminated.
          Character encoding is UTF-8.

          The cart number is a unsigned integer.

          The cart_type is 1=Audio,2=Macro. The default is Audio(1).

          The cart_grp_name must be a valid Rivendell DB Group.

          The cart_title is 255 characters Default is [new cart].

          The cart_artist is 255 characters. Default is NULL.

          The cart_album is 255 characters. Default is NULL.

          The cart_year is a date (YYYY). Default is NULL.

          The cart_label is 64 characters. Default is NULL.

          The cart_client is 64 characters. Default is NULL.

          The cart_agency is 64 characters. Default is NULL.

          The cart_publisher is 64 characters. Default is NULL.

          The cart_composer is 64 characters. Default is NULL.

          The cart_user_defined is 255 characters. Default is NULL.

          The cart_usage_code is  0=Feature (Default), 1=Theme Open,
                                  2=Theme Close, 3=Theme Open/Close,
                                  4=Background, 5=Comm/Promo

          The cart_forced_length is in milliseconds. Default is 0.

          The cart_average_length is in milliseconds. Default is 0.

          The cart_length_deviation is in milliseconds. Default is 0.

          The cart_average_segue_length is in milliseconds. Default is 0.

          The cart_average_hook_length is in milliseconds. Default is 0.

          The cart_cut_quantity is number of cuts. Default is 0.

          The cart_last_cut_played is self explanatory. Default is 0.

          The cart_validity is 0=NeverValid, 1=Conditional, 2=AlwaysValid (Default)
                               3=EvergreenValid, 4=FutureValid

          The cart_enforce_length is True(1) or False(0). Default is False(0).

          The cart_asyncronous is True(1) or False(0). Default is False(0).

          The cart_owner is 64 characters. Default is NULL.

          The cart_metadata_datetime is in tm struct format. Default is NULL.

          The cart_user_notes is a character array up to 1024 characters. Default is NULL

## RETURN VALUE

On success, zero is returned. Using the provided parameters an rd_cart structure is returned and the number of records is returned.

If a server error occurs a -1 is returned. If a client error occurs a specific error number is returned.

## ERRORS

400 Invalid Parameter for GROUP or TYPE.

400 Cart Already Exists.

403 User Authentification Error.

404 No Such Group Exists or Cart Out Of Range.

500 Unable to Create Cart.

nnn Unknown Error Occurred.