<?xml version="1.0" encoding="ISO-8859-1"?>
<refentry id="stdin" xmlns="http://docbook.org/ns/docbook" version="5.0">
<!--
Header
-->
<refmeta>
<refentrytitle>RD_EditCut</refentrytitle>
<manvolnum>7</manvolnum>
<refmiscinfo class='source'>October 2015</refmiscinfo>
<refmiscinfo class='manual'>Rivendell C Library Manual</refmiscinfo>
</refmeta>
<refnamediv>
<refname>rd_editcut</refname>
<refpurpose>Rivendell Edit Cut 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 <rivwebcapi/rd_editcut.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>RD_EditCut</function></funcdef>
<paramdef> struct rd_cut * <parameter>cut[]</parameter></paramdef>
<paramdef> struct edit_cut_values <parameter>edit_cut_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 unsigned <parameter>cutnumber</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_EditCut</command> is the function to use
to edit the fields within a cut that already exists in the Rivendell Database.
</para>
<para>
This function edits a pre-existing cut. User must provide the cart number, cut number and any fields which they would like to change. The structure edit_cut_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_cut
</entry>
<entry>
Pointer to rd_cut structure
</entry>
<entry>
Memory location to store cut information
</entry>
<entry>
Mandatory
</entry>
</row>
<row>
<entry>
edit_cut_values
</entry>
<entry>
edit_cut_values structure
</entry>
<entry>
This structure contains the new cut 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>
cutnumber
</entry>
<entry>
unsigned integer
</entry>
<entry>
Cut 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_cut_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_cut_values structure must be pre-filled with zeroes and has
the following format:
</para>
<programlisting>
struct edit_cut_values {
int cut_evergreen;
int use_cut_evergreen;
char cut_description[257];
int use_cut_description;
char cut_outcue[257];
int use_cut_outcue;
char cut_isrc[49];
int use_cut_isrc;
char cut_isci[129];
int use_cut_isci;
struct tm cut_start_datetime;
int use_cut_start_datetime;
struct tm cut_end_datetime;
int use_cut_end_datetime;
int cut_sun;
int use_cut_sun;
int cut_mon;
int use_cut_mon;
int cut_tue;
int use_cut_tue;
int cut_wed;
int use_cut_wed;
int cut_thu;
int use_cut_thu;
int cut_fri;
int use_cut_fri;
int cut_sat;
int use_cut_sat;
char cut_start_daypart[14];
int use_cut_start_daypart;
char cut_end_daypart[14];
int use_cut_end_daypart;
unsigned cut_weight;
int use_cut_weight;
unsigned cut_validity;
int use_cut_validity;
unsigned cut_coding_format;
int use_cut_coding_format;
unsigned cut_sample_rate;
int use_cut_sample_rate;
unsigned cut_bit_rate;
int use_cut_bit_rate;
unsigned cut_channels;
int use_cut_channels;
int cut_play_gain;
int use_cut_play_gain;
int cut_start_point;
int use_cut_start_point;
int cut_end_point;
int use_cut_end_point;
int cut_fadeup_point;
int use_cut_fadeup_point;
int cut_fadedown_point;
int use_cut_fadedown_point;
int cut_segue_start_point;
int use_cut_segue_start_point;
int cut_segue_end_point;
int use_cut_segue_end_point;
int cut_segue_gain;
int use_cut_segue_gain;
int cut_hook_start_point;
int use_cut_hook_start_point;
int cut_hook_end_point;
int use_cut_hook_end_point;
int cut_talk_start_point;
int use_cut_talk_start_point;
int cut_talk_end_point;
int use_cut_talk_end_point;
};
</programlisting>
<para>
When successful function will return the number of records sent (numrecs) and a rd_cut structure which
is stored in the provided memory locations. The rd_cut structure has the following fields:
</para>
<programlisting>
struct rd_cut {
char cut_name[11];
unsigned cut_cart_number;
unsigned cut_cut_number;
int cut_evergreen;
char cut_description[257];
char cut_outcue[257];
char cut_isrc[49];
char cut_isci[129];
unsigned cut_length;
struct tm cut_origin_datetime;
struct tm cut_start_datetime;
struct tm cut_end_datetime;
int cut_sun;
int cut_mon;
int cut_tue;
int cut_wed;
int cut_thu;
int cut_fri;
int cut_sat;
char cut_start_daypart[9];
char cut_end_daypart[9];
char cut_origin_name[257];
unsigned cut_weight;
struct tm cut_last_play_datetime;
unsigned cut_play_counter;
unsigned cut_local_counter;
unsigned cut_validity;
unsigned cut_coding_format;
unsigned cut_sample_rate;
unsigned cut_bit_rate;
unsigned cut_channels;
int cut_play_gain;
int cut_start_point;
int cut_end_point;
int cut_fadeup_point;
int cut_fadedown_point;
int cut_segue_start_point;
int cut_segue_end_point;
int cut_segue_gain;
int cut_hook_start_point;
int cut_hook_end_point;
int cut_talk_start_point;
int cut_talk_end_point;
};
All character arrays above are the sizes listed and are null-terminated.
Character encoding is UTF-8.
</programlisting>
</refsect1>
<refsect2 id='returns'><title>RETURN VALUE</title>
<para>
On success, zero is returned. Using the provided parameters an rd_cut
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 Parameter(s).
</para>
<para>
403 User Authentification Error.
</para>
<para>
403 Edit Audio Forbidden.
</para>
<para>
404 No Such Cart Exists.
</para>
<para>
nnn Unknown Error Occurred.
</para>
</refsect3>
</refentry>