<?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 &lt;rivwebcapi/rd_editcart.h&gt;</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[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;
    };
  </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[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.
      
  </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>
