interface.h File Reference

Low-level interface protocol manipulation routines. More...

Go to the source code of this file.

Classes
struct	Interface
struct	InterfaceNode
Defines
#define	INTERFACE_GETLU(p, k)   ((unsigned long)ATOUL(interface_get(p,k)))
#define	INTERFACE_GETLI(p, k)   ((signed long)ATOUL(interface_get(p,k)))
#define	INTERFACE_GETL(p, k)   INTERFACE_GETLI(p,k)
#define	INTERFACE_GETI(p, k)   ((int)(ATOI(interface_get(p,k))))
#define	INTERFACE_GETU(p, k)   ((unsigned int)(ATOI(interface_get(p,k))))
#define	INTERFACE_PUTLU(p, k, v)   interface_put(p, k, stringf ("%lu", (unsigned long)v))
#define	INTERFACE_PUTLI(p, k, v)   interface_put(p, k, stringf ("%li", (long)v))
#define	INTERFACE_PUTL(p, k, v)   INTERFACE_PUTLI(p,k,v)
#define	INTERFACE_PUTI(p, k, v)   interface_put(p, k, stringf ("%i", (int)v))
#define	INTERFACE_PUTU(p, k, v)   interface_put(p, k, stringf ("%u", (unsigned int)v))
Typedefs
typedef void(*	InterfaceForeach )(Interface *p, InterfaceNode *inode, void *udata)
Functions
LIBGIFT_EXPORT Interface *	interface_new (char *command, char *value)
LIBGIFT_EXPORT void	interface_free (Interface *p)
LIBGIFT_EXPORT void	interface_set_command (Interface *p, char *command)
LIBGIFT_EXPORT void	interface_set_value (Interface *p, char *value)
LIBGIFT_EXPORT char *	interface_get (Interface *p, char *key)
LIBGIFT_EXPORT BOOL	interface_put (Interface *p, char *key, char *value)
LIBGIFT_EXPORT void	interface_foreach (Interface *p, char *key, InterfaceForeach func, void *udata)
LIBGIFT_EXPORT void	interface_foreach_ex (Interface *p, InterfaceNode *node, InterfaceForeach func, void *udata)
LIBGIFT_EXPORT String *	interface_serialize (Interface *p)
LIBGIFT_EXPORT Interface *	interface_unserialize (char *data, size_t len)
LIBGIFT_EXPORT int	interface_send (Interface *p, TCPC *c)

---

Detailed Description

Low-level interface protocol manipulation routines.

---

Typedef Documentation

typedef void(* InterfaceForeach)(Interface *p, InterfaceNode *inode, void *udata)

Foreach callback for the Interface structure. Parameters: p  The Interface instance that requested this foreach action inode  Currently selected node element udata  User data supplied from interface_foreach.

---

Function Documentation

LIBGIFT_EXPORT void interface_foreach (  Interface *  p, char *  key, InterfaceForeach  func, void *  udata )

Loop through all interface elements that exists non-recursively at the key path specified by key. Parameters: p  key  Key path to begin searching from. A NULL value here will effectively loop through all base elements. func  Callback routine to be used for each element. udata  Arbitrary data to be given to each call of func.

LIBGIFT_EXPORT void interface_foreach_ex (  Interface *  p, InterfaceNode *  node, InterfaceForeach  func, void *  udata )

Loop through all interface elements given an interface node as a starting point. This is useful when it is necessary to manually implement loop recursion with interface_foreach, ie, you are trying to parse all SOURCE elements for a given transfer. See interface_foreach for more details. Parameters: p  node  Node given by a previous InterfaceForeach callback. func  udata

LIBGIFT_EXPORT void interface_free (  Interface *  p  )

Destroy a previously created instance.

LIBGIFT_EXPORT char* interface_get (  Interface *  p, char *  key )

Retrieve an interface element's value given a fully qualified key path. For example, if you wanted to get the Artist meta data for a given ITEM result (once parsed), you would use: printf ("ARTIST=%s\n", interface_get (p, "META/artist")); Parameters: p  key  Key path that references the desired interface element. Not case sensitive. Returns: The value as a string if found, otherwise NULL. Note that any key which has an empty value set will actually return a blank string (string literal "") instead of NULL.

LIBGIFT_EXPORT Interface* interface_new (  char *  command, char *  value )

Create a new instance intended for manual construction (generally this is used for data delivery, instead of parsing or handling). Parameters: command  value

LIBGIFT_EXPORT BOOL interface_put (  Interface *  p, char *  key, char *  value )

Add an interface element (key and value set) at the specified key path. See interface_get for more information on key paths. Parameters: p  key  Key path. value  Key data. Returns: Boolean success or failure. This function will return TRUE even if the inserted data already exists.

LIBGIFT_EXPORT int interface_send (  Interface *  p, TCPC *  c )

Simple abstract wrapper for delivering all the contents represented by an Interface instance to an established socket connection. Basically just serializes the data and schedules for delivery. Parameters: p  c  Returns: Total number of bytes delivered (or scheduled for delivery) on success, -1 on failure.

LIBGIFT_EXPORT String* interface_serialize (  Interface *  p  )

Flatten a fully constructed Interface instance into a simple String object. This is used prior to network delivery of the data represented by p. Parameters: p  Returns: String object containing the serialized data.

LIBGIFT_EXPORT void interface_set_command (  Interface *  p, char *  command )

Basic write accessor for the interface command.

LIBGIFT_EXPORT void interface_set_value (  Interface *  p, char *  value )

Basic write accessor for the interface command's value.

LIBGIFT_EXPORT Interface* interface_unserialize (  char *  data, size_t  len )

Parse a serialized interface object back into the high-level structure required for the API defined here to work. This is a required step for actually handling the data received over a socket. Parameters: data  Optionally NUL-terminated string similar to the return value of interface_serialize. Likely data received from some lower level network interface (eg, a socket). len  Length of data. Returns: Interface object pointer if successful, otherwise NULL.

---