mirror of
https://github.com/ElvishArtisan/rivendell.git
synced 2025-10-19 09:01:18 +02:00
2018-08-30 Fred Gleason <fredg@paravelsystems.com>
* Integrated the 'Rivendell-C-API' [from https://github.com/RadioFreeAsia/rivendell-c-api] in 'apis/rivwebcapi/'. * Added a 'rivendell-webapi' RPM subpackage.
This commit is contained in:
Fred Gleason
389
docs/rivwebcapi/rd_editcart.xml
Normal file
389
docs/rivwebcapi/rd_editcart.xml
Normal file
@@ -0,0 +1,389 @@
|
||||
<?xml version="1.0" encoding="ISO-8859-1"?>
|
||||
<refentry id="stdin" xmlns="http://docbook.org/ns/docbook" version="5.0">
|
||||
<!--
|
||||
Header
|
||||
-->
|
||||
<refmeta>
|
||||
<refentrytitle>RD_EditCart</refentrytitle>
|
||||
<manvolnum>7</manvolnum>
|
||||
<refmiscinfo class='source'>October 2015</refmiscinfo>
|
||||
<refmiscinfo class='manual'>Rivendell C Library Manual</refmiscinfo>
|
||||
</refmeta>
|
||||
<refnamediv>
|
||||
<refname>rd_editcart</refname>
|
||||
<refpurpose>Rivendell Edit Cart C Library Function</refpurpose>
|
||||
</refnamediv>
|
||||
<info>
|
||||
<author>
|
||||
<personname>
|
||||
<firstname>Todd</firstname>
|
||||
<surname>Baker</surname>
|
||||
<email>bakert@rfa.org</email>
|
||||
</personname>
|
||||
<contrib>Rivendell C Library Author</contrib>
|
||||
</author>
|
||||
</info>
|
||||
|
||||
<!--
|
||||
Body
|
||||
-->
|
||||
<refsynopsisdiv id='synopsis'>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <rivendell/rd_editcart.h></funcsynopsisinfo>
|
||||
<funcprototype>
|
||||
<funcdef>int <function>RD_EditCart</function></funcdef>
|
||||
<paramdef> struct rd_cart * <parameter>cart[]</parameter></paramdef>
|
||||
<paramdef> struct edit_cart_values <parameter>edit_cart_values</parameter></paramdef>
|
||||
<paramdef>const char <parameter>hostname[]</parameter></paramdef>
|
||||
<paramdef>const char <parameter>username[]</parameter></paramdef>
|
||||
<paramdef>const char <parameter>passwd[]</parameter></paramdef>
|
||||
<paramdef>const char <parameter>ticket[]</parameter></paramdef>
|
||||
<paramdef>const unsigned <parameter>cartnumber</parameter></paramdef>
|
||||
<paramdef>const char <parameter>user_agent[]</parameter></paramdef>
|
||||
<paramdef>unsigned * <parameter>numrecs</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1 id='description'><title>Description</title>
|
||||
<para>
|
||||
<command>RD_EditCart</command> is the function to use
|
||||
to edit the fields within a cart that already exists in the Rivendell Database.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<table xml:id="ex.editcart" frame="all">
|
||||
<title>RD_EditCart function call fields</title>
|
||||
<tgroup cols="4" align="left" colsep="1" rowsep="1">
|
||||
<colspec colname="FIELD NAME" />
|
||||
<colspec colname="FIELD TYPE" />
|
||||
<colspec colname="MEANING" />
|
||||
<colspec colname="REMARKS" />
|
||||
<thead>
|
||||
<row>
|
||||
<entry>
|
||||
FIELD NAME
|
||||
</entry>
|
||||
<entry>
|
||||
FIELD TYPE
|
||||
</entry>
|
||||
<entry>
|
||||
MEANING
|
||||
</entry>
|
||||
<entry>
|
||||
REMARKS
|
||||
</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>
|
||||
*rd_cart
|
||||
</entry>
|
||||
<entry>
|
||||
Pointer to rd_cart structure
|
||||
</entry>
|
||||
<entry>
|
||||
Memory location to store cart information
|
||||
</entry>
|
||||
<entry>
|
||||
Mandatory
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>
|
||||
edit_cart_values
|
||||
</entry>
|
||||
<entry>
|
||||
edit_cart_values structure
|
||||
</entry>
|
||||
<entry>
|
||||
This structure contains the new cart information to update
|
||||
</entry>
|
||||
<entry>
|
||||
Mandatory
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>
|
||||
hostname
|
||||
</entry>
|
||||
<entry>
|
||||
Character Array
|
||||
</entry>
|
||||
<entry>
|
||||
Name Of Rivendell DB Host
|
||||
</entry>
|
||||
<entry>
|
||||
Mandatory
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>
|
||||
username
|
||||
</entry>
|
||||
<entry>
|
||||
Character Array
|
||||
</entry>
|
||||
<entry>
|
||||
Rivendell User Name
|
||||
</entry>
|
||||
<entry>
|
||||
Mandatory When NO Ticket Provided
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>
|
||||
passwd
|
||||
</entry>
|
||||
<entry>
|
||||
Character Array
|
||||
</entry>
|
||||
<entry>
|
||||
Rivendell User Password
|
||||
</entry>
|
||||
<entry>
|
||||
Mandatory When NO Ticket Provided
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>
|
||||
ticket
|
||||
</entry>
|
||||
<entry>
|
||||
Character Array
|
||||
</entry>
|
||||
<entry>
|
||||
Rivendell Authentification Ticket
|
||||
</entry>
|
||||
<entry>
|
||||
Mandatory When NO User/Password Pair Provided.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>
|
||||
cartnumber
|
||||
</entry>
|
||||
<entry>
|
||||
unsigned integer
|
||||
</entry>
|
||||
<entry>
|
||||
Cart Number
|
||||
</entry>
|
||||
<entry>
|
||||
Mandatory
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>
|
||||
user_agent
|
||||
</entry>
|
||||
<entry>
|
||||
Character Array
|
||||
</entry>
|
||||
<entry>
|
||||
User Agent Value put into HTTP request
|
||||
</entry>
|
||||
<entry>
|
||||
Optional (default is Rivendell-C-API/x.x.x)
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>
|
||||
*numrecs
|
||||
</entry>
|
||||
<entry>
|
||||
pointer to integer
|
||||
</entry>
|
||||
<entry>
|
||||
memory location for number of records returned
|
||||
</entry>
|
||||
<entry>
|
||||
Mandatory
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
The edit_cart_values structure must be pre-filled with zeroes and has
|
||||
the following format:
|
||||
</para>
|
||||
<programlisting>
|
||||
struct edit_cart_values {
|
||||
char cart_grp_name[11];
|
||||
int use_cart_grp_name;
|
||||
char cart_title[256];
|
||||
int use_cart_title;
|
||||
char cart_artist[256];
|
||||
int use_cart_artist;
|
||||
char cart_album[256];
|
||||
int use_cart_album;
|
||||
int cart_year;
|
||||
int use_cart_year;
|
||||
char cart_label[65];
|
||||
int use_cart_label;
|
||||
char cart_client[65];
|
||||
int use_cart_client;
|
||||
char cart_agency[65];
|
||||
int use_cart_agency;
|
||||
char cart_publisher[65];
|
||||
int use_cart_publisher;
|
||||
char cart_composer[65];
|
||||
int use_cart_composer;
|
||||
char cart_conductor[65];
|
||||
int use_cart_conductor;
|
||||
char cart_user_defined[256];
|
||||
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[65];
|
||||
int use_cart_owner;
|
||||
char cart_notes[1024];
|
||||
int use_cart_notes;
|
||||
};
|
||||
</programlisting>
|
||||
<para>
|
||||
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:
|
||||
</para>
|
||||
<programlisting>
|
||||
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 */
|
||||
char cart_notes[1024]; /* Notes */
|
||||
};
|
||||
|
||||
All character arrays above are the sizes listed and are 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_user_notes is a character array up to 1024 characters.
|
||||
|
||||
</programlisting>
|
||||
|
||||
</refsect1>
|
||||
<refsect2 id='returns'><title>RETURN VALUE</title>
|
||||
<para>
|
||||
On success, zero is returned. Using the provided parameters an rd_cart
|
||||
structure is returned and the number of records is returned.
|
||||
</para>
|
||||
<para>
|
||||
If a server error occurs a -1 is returned.
|
||||
If a client error occurs a specific error number is returned.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect3 id='errors'><title>ERRORS</title>
|
||||
<para>
|
||||
400 Invalid Input Parameter.
|
||||
</para>
|
||||
<para>
|
||||
403 User Authentification Error.
|
||||
</para>
|
||||
<para>
|
||||
404 Unauthorized or No Such Group / Cart Exists.
|
||||
</para>
|
||||
<para>
|
||||
409 Cart Out Of Range.
|
||||
</para>
|
||||
<para>
|
||||
500 Unable to Create Cart.
|
||||
</para>
|
||||
<para>
|
||||
nnn Unknown Error Occurred.
|
||||
</para>
|
||||
</refsect3>
|
||||
|
||||
</refentry>
|
||||
Reference in New Issue
Block a user