RD_EditCart 7 October 2015 Rivendell C Library Manual rd_editcart Rivendell Edit Cart C Library Function Todd Baker bakert@rfa.org Rivendell C Library Author #include <rivwebcapi/rd_editcart.h> int RD_EditCart struct rd_cart * cart[] struct edit_cart_values edit_cart_values const char hostname[] const char username[] const char passwd[] const char ticket[] const unsigned cartnumber const char user_agent[] unsigned * numrecs RD_EditCart is the function to use to edit the fields within a cart that already exists in the Rivendell Database. This function edits a pre-existing cart. User must provide the cart number and any fields which they would like to change. The structure edit_cart_values must be used to tell the API which fields will be changed. FIELD NAME FIELD TYPE MEANING REMARKS *rd_cart Pointer to rd_cart structure Memory location to store cart information Mandatory edit_cart_values edit_cart_values structure This structure contains the new cart information to update 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. 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 This routine expects an input structure of type edit_cart_values - listed below. Each field has a boolean flag field (starting with use_) which designates whether to update the field's value or not. One (1) = true - Use the value in the field or Zero (0) - Ignore the field. The edit_cart_values structure must be pre-filled with zeroes and has the following format: struct edit_cart_values { char cart_grp_name[41]; int use_cart_grp_name; char cart_title[1021]; int use_cart_title; char cart_artist[1021]; int use_cart_artist; char cart_album[1021]; int use_cart_album; int cart_year; int use_cart_year; char cart_label[257]; int use_cart_label; char cart_client[257]; int use_cart_client; char cart_agency[257]; int use_cart_agency; char cart_publisher[257]; int use_cart_publisher; char cart_composer[257]; int use_cart_composer; char cart_conductor[257]; int use_cart_conductor; char cart_user_defined[1021]; int use_cart_user_defined; int cart_usage_code; int use_cart_usage_code; int cart_forced_length; int use_cart_forced_length; int cart_enforce_length; int use_cart_enforce_length; int cart_asyncronous; int use_cart_asyncronous; char cart_owner[257]; int use_cart_owner; char cart_notes[4096]; int use_cart_notes; }; 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_conductor[257]; /* Conductor */ 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 */ char cart_notes[4096]; /* 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 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_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. 400 Invalid Input Parameter. 403 User Authentification Error. 404 Unauthorized or No Such Group / Cart Exists. 409 Cart Out Of Range. 500 Unable to Create Cart. nnn Unknown Error Occurred.