/*
** Copyright 2000-2004 University of Illinois Board of Trustees
** Copyright 2000-2004 Mark D. Roth
** All rights reserved.
**
** phclient.h - main header file for libphclient
**
** Mark D. Roth <roth@feep.net>
*/
#ifndef PHCLIENT_H
#define PHCLIENT_H
/* general return values */
#define PH_ERR_NOTLOG -2 /* not logged in */
#define PH_ERR_NOTHERO -3 /* not hero */
#define PH_ERR_DATAERR -4 /* invalid field data */
#define PH_ERR_NOMATCH -5 /* no matching entries found */
#define PH_ERR_TOOMANY -6 /* too many entries matched */
#define PH_ERR_READONLY -7 /* database is read-only */
/* PH server handle */
typedef struct ph_handle PH;
/***** auth.c **********************************************************/
/* macros for ph_login()'s authtype argument */
#ifdef PHLIB_XLOGIN /* not currently supported */
# define PH_AUTH_FWTK 4 /* TIS authsrv */
# define PH_AUTH_KRB4 8 /* Kerberos 4 */
# define PH_AUTH_KRB5 16 /* Kerberos 5 */
# define PH_AUTH_GSS 32 /* GSS-API */
#endif
#define PH_AUTH_EMAIL 64 /* email field */
#define PH_AUTH_PASSWORD 128 /* encrypted password */
#define PH_AUTH_CLEAR 256 /* cleartext password */
/*
** ph_login() - login to the PH server.
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_NOTLOG authentication denied
*/
int ph_login(PH *, char *, int, void *);
/*
** ph_logout() - logout of the PH server.
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_NOTLOG not logged in
*/
int ph_logout(PH *);
/*
** ph_suser() - assume another user's identity (heros only).
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_NOTHERO not a hero
** PH_ERR_NOTLOG not logged in
*/
int ph_suser(PH *, char *);
/*
** ph_passwd() - change the current user's PH password.
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_NOTLOG not logged in
*/
int ph_passwd(PH *, char *);
/*
** ph_whoami() - determine the currently logged-in alias
** returns:
** pointer to the current alias success
** NULL not logged in
*/
char *ph_whoami(PH *);
/***** change.c ********************************************************/
/* representation of a field selector */
struct ph_fieldselector
{
char *pfs_field;
char pfs_operation; /* must be '=', '~', '>', or '<' */
char *pfs_value;
};
/* flags for ph_change() */
#define PH_CHANGE_FORCE 1 /* use "force" instead of "make" */
/*
** ph_change() - change a PH entry.
** returns:
** number of entries changed success
** -1 error (sets errno)
** PH_ERR_NOTLOG not logged in
** PH_ERR_DATAERR invalid field data
*/
int ph_change(PH *, struct ph_fieldselector[], struct ph_fieldselector[], int);
/*
** ph_add() - add a PH entry.
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_NOTLOG not logged in
** PH_ERR_DATAERR invalid field data
*/
int ph_add(PH *, struct ph_fieldselector[]);
/*
** ph_delete() - delete a PH entry.
** returns:
** number of entries deleted success
** -1 error (sets errno)
** PH_ERR_NOTLOG not logged in
*/
int ph_delete(PH *, struct ph_fieldselector[]);
/***** fields.c ********************************************************/
/* values for attribute bitmask */
#define PH_ATTRIB_ALWAYS 1
#define PH_ATTRIB_ANY 2
#define PH_ATTRIB_CHANGE 4
#define PH_ATTRIB_DEFAULT 8
#define PH_ATTRIB_ENCRYPT 16
#define PH_ATTRIB_FORCEPUB 32
#define PH_ATTRIB_INDEXED 64
#define PH_ATTRIB_LOCALPUB 128
#define PH_ATTRIB_LOOKUP 256
#define PH_ATTRIB_NOMETA 512
#define PH_ATTRIB_NOPEOPLE 1024
#define PH_ATTRIB_PRIVATE 2048
#define PH_ATTRIB_PUBLIC 4096
#define PH_ATTRIB_SACRED 8192
#define PH_ATTRIB_TURN 16384
#define PH_ATTRIB_UNIQUE 32768
#define PH_ATTRIB_PRIVLOOKUP 65536
#define PH_ATTRIB_SACREDPERSON 131072
/* fields supported by the server */
struct ph_fieldinfo
{
int pf_id;
char **pf_fnames;
int pf_max_size;
char *pf_description;
unsigned long pf_attrib;
};
/*
** ph_retrieve_fieldinfo() - obtain a list of fields supported by the PH server.
** returns:
** 0 success
** -1 error (sets errno)
*/
int ph_retrieve_fieldinfo(PH *);
/*
** writes a string of space-delimited attribute names corresponding to
** the numeric bitmask
*/
void ph_decode_field_attributes(unsigned long, char *, size_t);
/*
** ph_get_fieldinfo() - return the description for a given field.
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_DATAERR unknown field
*/
int ph_get_fieldinfo(PH *, char *, struct ph_fieldinfo **);
/*
** ph_fieldinfo_iterate() - return the next field info structure.
** returns:
** 1 data returned
** 0 no more data
** -1 error (sets errno)
*/
int ph_fieldinfo_iterate(PH *, struct ph_fieldinfo **);
/*
** ph_free_fieldinfo() - free fieldlist associated with ph.
*/
void ph_free_fieldinfo(PH *);
/*
** ph_is_fieldlist_cached() - check if field list is cached.
** returns:
** 0 not cached
** 1 cached
*/
int ph_is_fieldlist_cached(PH *);
/***** handle.c *******************************************************/
extern const char libphclient_version[];
extern const int libphclient_is_thread_safe;
/* typedef for debug hooks */
typedef void (*ph_debug_func_t)(void *, char *);
/* flags for ph_open() */
#define PH_OPEN_PRIVPORT 1 /* connect from a priveledged port */
#define PH_OPEN_ROUNDROBIN 2 /* try all addresses of a DNS
round-robin before failing */
#define PH_OPEN_LOCAL 4 /* open pipe to local PH server
process */
#define PH_OPEN_DONTID 8 /* don't identify library version
to server */
/* flags for ph_close() */
#define PH_CLOSE_FAST 1 /* drop connection without sending
"quit" */
/*
** ph_open() - opens a connection to the PH server.
** returns:
** 0 success
** -1 error (sets errno)
*/
int ph_open(PH **, char *, int, ph_debug_func_t, ph_debug_func_t, void *);
/*
** ph_close() - closes a connection to the PH server.
** 0 success
** -1 error (sets errno)
*/
int ph_close(PH *, int);
/*
** ph_rfd() - return the read file descriptor associated with the PH handle.
*/
int ph_rfd(PH *);
/*
** ph_wfd() - return the write file descriptor associated with the PH handle.
*/
int ph_wfd(PH *);
/***** misc.c **********************************************************/
/*
** ph_id() - send id command to server.
** returns:
** 0 success
** -1 error (sets errno)
*/
int ph_id(PH *, char *);
/*
** ph_status() - get status info.
** 0 success
** -1 error (sets errno)
*/
int ph_status(PH *, char **);
/*
** ph_external() - send "external" command.
** 0 success
** -1 error (sets errno)
*/
int ph_external(PH *);
/***** options.c *******************************************************/
/* options supported by the server */
struct ph_option
{
char *po_option;
char *po_setting;
};
/*
** ph_retrieve_options() - obtain options from server.
** 0 success
** -1 error (sets errno)
*/
int ph_retrieve_options(PH *);
/*
** ph_set_option() - set an option on the server.
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_DATAERR no such option
*/
int ph_set_option(PH *, char *, char *);
/*
** ph_get_option() - obtain the current setting of a given option.
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_DATAERR no such option
*/
int ph_get_option(PH *, char *, char **);
/*
** ph_option_iterate() - iterate through server option list.
** returns:
** 1 data returned
** 0 no more data
** -1 error (sets errno)
*/
int ph_option_iterate(PH *, struct ph_option **);
/*
** ph_free_options() - free option list associated with PH handle ph.
*/
void ph_free_options(PH *);
/*
** ph_is_optionlist_cached() - check if option list is cached.
** returns:
** 0 not cached
** 1 cached
*/
int ph_is_optionlist_cached(PH *);
/***** protocol.c ******************************************************/
/*
** server reply codes (from qi distribution):
** 1XX - status
** 2XX - information
** 3XX - additional information or action needed
** 4XX - temporary errors
** 5XX - permanent errors
*/
#define LR_PROGRESS 100 /* in progress */
#define LR_ECHO 101 /* echoing cmd */
#define LR_NUMRET 102 /* how many entries are being returned */
#define LR_NONAME 103 /* no hostname found for IP address */
#define LR_OK 200 /* success */
#define LR_RONLY 201 /* database ready in read only mode */
#define LR_MORE 300 /* need more info */
#define LR_LOGIN 301 /* encrypt this string */
#define LR_XLOGIN 302 /* print this prompt */
#define LR_TEMP 400 /* temporary error */
#define LR_INTERNAL 401 /* database error, possibly temporary */
#define LR_LOCK 402 /* lock not obtained within timeout period */
#define LR_COULDA_BEEN 403 /* login would have been ok but db read only */
#define LR_DOWN 475 /* database unavailable; try again later */
#define LR_ERROR 500 /* hard error; general */
#define LR_NOMATCH 501 /* no matches to query */
#define LR_TOOMANY 502 /* too many matches to query */
#define LR_AINFO 503 /* may not see that field */
#define LR_ASEARCH 504 /* may not search on that field */
#define LR_ACHANGE 505 /* may not change field */
#define LR_NOTLOG 506 /* must be logged in */
#define LR_FIELD 507 /* field unknown */
#define LR_ABSENT 508 /* field not present in entry */
#define LR_ALIAS 509 /* requested alias is already in use */
#define LR_AENTRY 510 /* may not change entry */
#define LR_ADD 511 /* may not add entries */
#define LR_VALUE 512 /* illegal value */
#define LR_OPTION 513 /* unknown option */
#define LR_UNKNOWN 514 /* unknown command */
#define LR_NOKEY 515 /* no indexed field found in query */
#define LR_AUTH 516 /* no authorization for query */
#define LR_READONLY 517 /* operation failed; database is read-only */
#define LR_LIMIT 518 /* too many entries selected for change */
#define LR_HISTORY 519 /* history substitution failed (obsolete) */
#define LR_XCPU 520 /* too much cpu used */
#define LR_ADDONLY 521 /* addonly option set and change command
applied to a field with data */
#define LR_ISCRYPT 522 /* attempt to view encrypted field */
#define LR_NOANSWER 523 /* "answer" was expected but not gotten */
#define LR_BADHELP 524 /* help topics cannot contain slashes */
#define LR_NOEMAIL 525 /* email authentication failed */
#define LR_NOADDR 526 /* host name address not found in DNS */
#define LR_MISMATCH 527 /* host = gethostbyaddr(foo); foo != gethostbyname(host) */
#define LR_KDB5 528 /* general kerberos database error */
#define LR_NOAUTH 529 /* selected authentication method not avail */
#define LR_NOCMD 598 /* no such command */
#define LR_SYNTAX 599 /* syntax error */
/*
** ph_set_sendhook() - set the send hook function.
*/
void ph_set_sendhook(PH *, ph_debug_func_t);
/*
** ph_set_recvhook() - set the receive hook function.
*/
void ph_set_recvhook(PH *, ph_debug_func_t);
/*
** ph_set_hookdata() - set the hook data to be passed to the debug hooks
*/
void ph_set_hookdata(PH *, void *);
/*
** ph_encode_selector() - parse the selector string and add an entry to
** the selectors array.
** returns:
** 0 success
** -1 parse error
*/
int ph_encode_selector(char *, int, int *, struct ph_fieldselector **);
/*
** ph_free_selectors() - free memory associated with an array of selectors
*/
void ph_free_selectors(struct ph_fieldselector *);
/***** query.c *********************************************************/
struct ph_fieldvalue
{
int pfv_code;
char *pfv_field;
char *pfv_value;
};
typedef struct ph_fieldvalue *ph_entry;
/*
** ph_query() - send a query to the PH server and return matching entries.
** returns:
** number of entries returned success
** -1 error (sets errno)
** PH_ERR_TOOMANY too many entries matched
** PH_ERR_NOMATCH no matching entries
** PH_ERR_DATAERR invalid query
*/
int ph_query(PH *, struct ph_fieldselector[], char *[],
ph_entry **);
/*
** ph_free_entries() - free memory returned by ph_query().
*/
void ph_free_entries(ph_entry *);
/***** redirection.c **************************************************/
/*
** ph_advertised_email() - returns alias-based email address for alias
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_NOMATCH alias does not exist
** PH_ERR_DATAERR no email field
*/
int ph_advertised_email(PH *, char *, int, char **);
/*
** ph_email_resolve() - returns the expanded email address for user
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_NOMATCH no single match found
** PH_ERR_DATAERR no email field
*/
int ph_email_resolve(PH *, char *, char *, char **);
/*
** ph_advertised_www() - returns alias-based URL for alias
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_NOMATCH alias does not exist
** PH_ERR_DATAERR no www field
*/
int ph_advertised_www(PH *, char *, int, char **);
/*
** ph_www_resolve() - returns the expanded URL for user
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_NOMATCH no single entry matched
** PH_ERR_DATAERR no www field
*/
int ph_www_resolve(PH *, char *, char **);
/***** serverlist.c ****************************************************/
/* structure to describe other PH servers */
struct ph_serversite
{
char *ss_server;
char *ss_site;
};
struct ph_serverlist
{
struct ph_serversite *sl_list;
unsigned int sl_numservers;
};
/*
** ph_serverlist_add() - add an entry to a list of known PH servers.
** returns:
** 0 success
** -1 error (sets errno)
*/
int ph_serverlist_add(struct ph_serverlist *, char *, char *);
/*
** ph_serverlist_iterate() - iterate through all matching PH server entries.
** returns:
** 1 data returned
** 0 no more data
** -1 error (sets errno)
*/
int ph_serverlist_iterate(struct ph_serverlist *, char *, char *,
struct ph_serversite **);
/*
** ph_serverlist_merge() - read list of known PH servers from the server
** associated with ph and merge them into serverlist.
** returns:
** 0 success
** -1 error (sets errno)
*/
int ph_serverlist_merge(PH *, struct ph_serverlist *);
/*
** ph_free_serverlist() - free memory associated with serverlist.
*/
void ph_free_serverlist(struct ph_serverlist *);
/***** siteinfo.c ******************************************************/
/* siteinfo provided by the server */
struct ph_siteinfo
{
char *ps_info;
char *ps_data;
};
/*
** ph_retrieve_siteinfo() - read siteinfo from server.
** returns:
** 0 success
** -1 error (sets errno)
*/
int ph_retrieve_siteinfo(PH *);
/*
** ph_get_siteinfo() - return the value of a specific info field.
** returns:
** 0 success
** -1 error (sets errno)
** PH_ERR_DATAERR unknown siteinfo field
*/
int ph_get_siteinfo(PH *, char *, char **);
/*
** ph_siteinfo_iterate() - iterate through siteinfo list.
** returns:
** 1 data returned
** 0 no more data
** -1 error (sets errno)
*/
int ph_siteinfo_iterate(PH *, struct ph_siteinfo **);
/*
** ph_free_siteinfo() - free the siteinfo list associated with ph.
*/
void ph_free_siteinfo(PH *);
/*
** ph_is_siteinfo_cached() - check if siteinfo data is cached.
** returns:
** 0 not cached
** 1 cached
*/
int ph_is_siteinfo_cached(PH *);
#endif /* PHCLIENT_H */
syntax highlighted by Code2HTML, v. 0.9.1