ph_get_siteinfo(3)

NAME
ph_retrieve_siteinfo, ph_get_siteinfo, ph_siteinfo_iterate - access site-specific information from PH server

SYNOPSIS
#include <phclient.h>

int ph_get_siteinfo(PH *ph, char *info, char **data);
int ph_retrieve_siteinfo(PH *ph);
int ph_siteinfo_iterate(PH *ph, struct ph_siteinfo **siteinfo);
void ph_free_siteinfo(PH *ph);
int ph_is_siteinfo_cached(PH *ph);

VERSION
This man page documents version 1.2 of libphclient.

DESCRIPTION
These functions allow the caller to access the list of site-specific settings from the PH server associated with the PH handle ph. Site-specific settings are represented as ph_siteinfo structures, which contain the following fields: info (the name of the field, encoded as a string) and data (the string encoding of the data contained in the field). The ph_retrieve_siteinfo() function retrieves the siteinfo list from the PH server to be cached locally. If the siteinfo data is already cached locally, the function returns successfully without doing anything. The ph_free_siteinfo() function clears the local siteinfo cache. A subsequent call to ph_retrieve_siteinfo() will reload the siteinfo data from the server. The ph_is_siteinfo_cached() macro determines whether or not the siteinfo data is cached locally. The ph_get_siteinfo() function sets data to point to the value of the siteinfo field named by info. It automatically calls ph_retrieve_siteinfo() if the siteinfo data is not cached locally. The ph_siteinfo_iterate() function allows the caller to cycle through the list of siteinfo entries by setting siteinfo to point to the next entry on each successive call. To start at the beginning of the list, the caller initializes siteinfo to NULL.

RETURN VALUE
The ph_retrieve_siteinfo() function returns 0 on success, or -1 on error and sets errno. The ph_is_siteinfo_cached() macro returns 1 if the siteinfo data is cached locally, or 0 otherwise. The ph_get_siteinfo() function returns 0 on success, -1 on error, or PH_ERR_DATAERR if there is no entry for info. The ph_siteinfo_iterate() function returns 1 when the next siteinfo entry is returned, 0 at the end of the list, or -1 on error (and sets errno).

ERRORS
The ph_retrieve_siteinfo() function will fail with EINVAL if it receives an unexpected response code from the server. The ph_retrieve_siteinfo() function may fail with any error from the functions read() or write().

SEE ALSO
read(2), write(2), ph_open(3)