.TH ph_get_siteinfo 3 "Oct 2002" "University of Illinois" "C Library Calls"
.SH NAME
ph_retrieve_siteinfo, ph_get_siteinfo, ph_siteinfo_iterate \- access site-specific information from PH server
.SH SYNOPSIS
.B #include <phclient.h>
.P
.BI "int ph_get_siteinfo(PH *" ph ", char *" info ","
.BI "char **" data ");"
.br
.BI "int ph_retrieve_siteinfo(PH *" ph ");"
.br
.BI "int ph_siteinfo_iterate(PH *" ph ", struct ph_siteinfo **" siteinfo ");"
.br
.BI "void ph_free_siteinfo(PH *" ph ");"
.br
.BI "int ph_is_siteinfo_cached(PH *" ph ");"
.SH VERSION
This man page documents version 1.2 of \fBlibphclient\fP.
.SH DESCRIPTION
These functions allow the caller to access the list of site-specific
settings from the PH server associated with the \fBPH\fP handle \fIph\fP.
Site-specific settings are represented as \fIph_siteinfo\fP structures,
which contain the following fields: \fIinfo\fP (the name of the field,
encoded as a string) and \fIdata\fP (the string encoding of the data
contained in the field).

The \fBph_retrieve_siteinfo\fP() 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 \fBph_free_siteinfo\fP() function clears the local siteinfo cache.
A subsequent call to \fBph_retrieve_siteinfo\fP() will reload the siteinfo
data from the server.

The \fBph_is_siteinfo_cached\fP() macro determines whether or not the
siteinfo data is cached locally.

The \fBph_get_siteinfo\fP() function sets \fIdata\fP to point to the value
of the siteinfo field named by \fIinfo\fP.  It automatically calls
\fBph_retrieve_siteinfo\fP() if the siteinfo data is not cached locally.

The \fBph_siteinfo_iterate\fP() function allows the caller to cycle
through the list of siteinfo entries by setting \fIsiteinfo\fP to
point to the next entry on each successive call.  To start at the beginning
of the list, the caller initializes \fIsiteinfo\fP to \fBNULL\fP.
.SH RETURN VALUE
The \fBph_retrieve_siteinfo\fP() function returns 0 on success, or -1 on error
and sets \fIerrno\fP.

The \fBph_is_siteinfo_cached\fP() macro returns 1 if the siteinfo data is
cached locally, or 0 otherwise.

The \fBph_get_siteinfo\fP() function returns 0 on success, -1 on error,
or \fIPH_ERR_DATAERR\fP if there is no entry for \fIinfo\fP.

The \fBph_siteinfo_iterate\fP() function returns 1 when the next siteinfo
entry is returned, 0 at the end of the list, or -1 on error (and sets
\fIerrno\fP).
.SH ERRORS
The \fBph_retrieve_siteinfo\fP() function will fail with \fBEINVAL\fP if it
receives an unexpected response code from the server.

The \fBph_retrieve_siteinfo\fP() function may fail with any error from the
functions \fIread\fP() or \fIwrite\fP().
.SH SEE ALSO
.BR read (2),
.BR write (2),
.BR ph_open (3)