RD_ListCarts 7 October 2015 Rivendell C Library Manual rd_listcarts Rivendell List Carts C Library Function Todd Baker bakert@rfa.org Rivendell C Library Author #include <rivendell/rd_listcarts.h> int RD_ListCarts struct rd_cart * cart[] const char hostname[] const char username[] const char passwd[] const char ticket[] const char group_name[] const char filter[] const char type[] const char user_agent[] unsigned * numrecs RD_ListCarts is the function to use to list the carts that already exists in the Rivendell Database. This function lists the fields in a pre-existing cart. The user can also filter the records by group name, cart type, and/or a user provided search string. FIELD NAME FIELD TYPE MEANING REMARKS *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_name character array Group Name Optional filter character array Filter - searches for specific strings within the following fields: Title, Artist, Client, Agency, Album, Label, Publisher, Composer, Conductor, Song_Id, User_Defined, and Cart Number. Optional type character array Type of Cart records. If set can be Audio, or Macro. Optional 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[11]; /* Group Name */ char cart_title[256]; /* Cart Title */ char cart_artist[256]; /* Artist */ char cart_album[256]; /* Album */ int cart_year; /* Year */ char cart_label[65]; /* Label */ char cart_client[65]; /* Client */ char cart_agency[65]; /* Agency */ char cart_publisher[65]; /* Publisher */ char cart_composer[65]; /* Composer */ char cart_conductor[65]; /* Conductor */ char cart_user_defined[256]; /* 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[65]; /* Owner */ struct tm cart_metadata_datetime; /* Metatdata Datetime */ char cart_notes[1024]; /* Notes */ }; All character arrays above are the sizes listed and must be null-terminated. The cart number is a unsigned integer. The cart_type is 1=Audio,2=Macro. The cart_grp_name must be a valid Rivendell DB Group. The cart_title is 255 characters. The cart_artist is 255 characters. The cart_album is 255 characters. The cart_year is a date (YYYY). The cart_label is 64 characters. The cart_client is 64 characters. The cart_agency is 64 characters. The cart_publisher is 64 characters. The cart_composer is 64 characters. The cart_conductor is 64 characters. The cart_user_defined is 255 characters. The cart_usage_code is 0=Feature, 1=Theme Open, 2=Theme Close, 3=Theme Open/Close, 4=Background, 5=Comm/Promo The cart_forced_length is in milliseconds. The cart_average_length is in milliseconds. The cart_length_deviation is in milliseconds. The cart_average_segue_length is in milliseconds. The cart_average_hook_length is in milliseconds. The cart_cut_quantity is number of cuts. The cart_last_cut_played is self explanatory. The cart_validity is 0=NeverValid, 1=Conditional, 2=AlwaysValid 3=EvergreenValid, 4=FutureValid The cart_enforce_length is True(1) or False(0). The cart_asyncronous is True(1) or False(0). The cart_owner is 64 characters. The cart_metadata_datetime is a struct tm. The cart_user_notes is a character array up to 1024 characters. 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. 403 User Authentification Error. 404 No Such Group Exists. nnn Unknown Error Occurred.