RD_ListGroup
7
October 2015
Rivendell C Library Manual

# rd_listgroup

Rivendell List Group C Library Function
Todd
Baker
bakert@rfa.org
Rivendell C Library Author

        #include <rivwebcapi/rd_listgroup.h>

        int RD_ListGroup
           struct rd_group * group[]
          const char hostname[]
          const char username[]
          const char passwd[]
          const char ticket[]
          const char groupname[]
          const char user_agent[]
          unsigned * numrecs

## Description

`RD_ListGroup` is the function to use to list the fields that are stored for a particular group within the Rivendell Database.

This function lists the fields in a pre-existing Group.

### RD_ListGroup function call fields

FIELD NAME | FIELD TYPE | MEANING | REMARKS
--- | --- | --- | ---
*group | Pointer to rd_group structure | Memory location to store group 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.
groupname | character array | Group Name | 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

When successful function will return the number of records sent (numrecs) and a rd_group structure which is stored in the provided memory locations. The rd_group structure has the following fields:

    struct rd_group {
      char grp_name[41];			/* Group Name */
      char grp_desc[1021];			/* Description */
      unsigned grp_default_cart_type;	/* Default cart type */
      unsigned grp_lo_limit;		/* Group starting Cart Number */
      unsigned grp_hi_limit;		/* Group Ending Cart Number */
      int grp_shelf_life;
      char grp_default_title[1021];
      int grp_enforce_range;
      int grp_report_tfc;
      int grp_report_mus;
      int grp_now_next;
      char grp_color[8];
      char grp_reserved[457];
    };

          All character arrays above are the sizes listed and must be null-terminated.

          The cart number is a unsigned integer.

          The Default cart_type is 1=Audio,2=Macro.

## RETURN VALUE

On success, zero is returned. Using the provided parameters an rd_group 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.

## ERRORS

400 Missing Group Name.

403 User Authentification Error.

404 No Such Group Exists.

nnn Unknown Error Occurred.