From: Jan Pospíšil Date: Fri, 25 Feb 2005 18:05:29 +0000 (+0000) Subject: Updated documentation. X-Git-Tag: glite-lb-client-interface_R_1_0_2~40 X-Git-Url: http://scientific.zcu.cz/git/?a=commitdiff_plain;h=abed5c3d52bee3afb51b887add6c89059f8c0a63;p=jra1mw.git Updated documentation. - created several doxygen groups (documentation modules) - eliminated many doxygen warnings --- diff --git a/org.glite.lb.client-interface/interface/Event.h.T b/org.glite.lb.client-interface/interface/Event.h.T index fa077a0..3365576 100644 --- a/org.glite.lb.client-interface/interface/Event.h.T +++ b/org.glite.lb.client-interface/interface/Event.h.T @@ -187,7 +187,7 @@ public: * \throw Exception Invalid event type or attribute not * defined for this event. */ - int getValInt(Attr) const; + int getValInt(Attr name) const; /** Retrieve string attribute. * @@ -197,7 +197,7 @@ public: * \throw Exception Invalid event type or attribute not * defined for this event. */ - std::string getValString(Attr) const; + std::string getValString(Attr name) const; /** Retrieve time attribute. * @@ -205,7 +205,7 @@ public: * \param[in] name Name of the attribute to retrieve. * \returns struct timeval value of the attribute. */ - struct timeval getValTime(Attr) const; + struct timeval getValTime(Attr name) const; /** Retrieve jobid attribute * @@ -215,7 +215,7 @@ public: * \throw Exception Invalid event type or attribute not * defined for this event. */ - const glite::wmsutils::jobid::JobId getValJobId(Attr) const; + const glite::wmsutils::jobid::JobId getValJobId(Attr name) const; /** Attribute name. * @@ -225,7 +225,7 @@ public: * \throw Exception Invalid event type or attribute not * defined for this event. */ - const std::string & getAttrName(Attr) const; + const std::string & getAttrName(Attr name) const; /** List of attributes and types valid for this instance. * diff --git a/org.glite.lb.client-interface/interface/consumer.h b/org.glite.lb.client-interface/interface/consumer.h index d34c6de..67af264 100644 --- a/org.glite.lb.client-interface/interface/consumer.h +++ b/org.glite.lb.client-interface/interface/consumer.h @@ -4,15 +4,6 @@ /*! * \file consumer.h * \brief L&B consumer API - * - * General rules: - * - functions return 0 on success, nonzero on error, errror details can - * be found via edg_wll_ErrorCode() - * - OUT are ** types, functions malloc()-ate objects and fill in the pointer - * pointed to by the OUT argument - * - returned lists of pointers are NULL-terminated malloc()-ed arrays - * - edg_wll_Query + wrapper terminate arrays with EDG_WLL_EVENT_UNDEF event - * - OUT is NULL if the list is empty */ #ident "$Header$" @@ -26,7 +17,22 @@ extern "C" { #endif -/*! +/** + * \defgroup querying Server querying + * \brief Query server record description and handling. + * + * General rules: + * - functions return 0 on success, nonzero on error, errror details can + * be found via edg_wll_ErrorCode() + * - OUT are ** types, functions malloc()-ate objects and fill in the pointer + * pointed to by the OUT argument + * - returned lists of pointers are NULL-terminated malloc()-ed arrays + * - edg_wll_Query + wrapper terminate arrays with EDG_WLL_EVENT_UNDEF event + * - OUT is NULL if the list is empty + *@{ + */ + +/** * Predefined types for query attributes */ typedef enum _edg_wll_QueryAttr{ @@ -53,7 +59,7 @@ typedef enum _edg_wll_QueryAttr{ } edg_wll_QueryAttr; -/*! +/** * Predefined types for query operands */ typedef enum _edg_wll_QueryOp{ @@ -65,7 +71,7 @@ typedef enum _edg_wll_QueryOp{ } edg_wll_QueryOp; -/*! +/** * Single query condition for edg_wll_Query(). * Those records are composed to form an SQL \a where clause * when processed at the L&B server @@ -93,36 +99,15 @@ typedef struct _edg_wll_QueryRec { } value, value2; } edg_wll_QueryRec; -/************************************************ - * API FUNCTION DECLARATIONS * +/** + * default query timeout (in seconds) */ - - -#ifdef CLIENT_SBIN_PROG -extern int edg_wll_http_send_recv( - edg_wll_Context, - char *, const char * const *, char *, - char **,char ***,char ** -); - -extern int http_check_status( - edg_wll_Context, - char *, - char ** -); - -extern int set_server_name_and_port( - edg_wll_Context, - const edg_wll_QueryRec ** -); - -#endif +#define EDG_WLL_QUERY_TIMEOUT_DEFAULT 120 /** - * \name Server querying - * - *@{ + * maximal query timeout (in seconds) */ +#define EDG_WLL_QUERY_TIMEOUT_MAX 1800 /** * General query on events. @@ -369,8 +354,6 @@ int edg_wll_QuerySequenceCodeProxy( char ** code ); -/*@}*/ - /* * edg_wll_QueryRec manipulation */ @@ -378,17 +361,29 @@ int edg_wll_QuerySequenceCodeProxy( /** Free edg_wll_QueryRec internals, not the structure itself */ void edg_wll_QueryRecFree(edg_wll_QueryRec *); +/* + *@} end of group + */ + +#ifdef CLIENT_SBIN_PROG +extern int edg_wll_http_send_recv( + edg_wll_Context, + char *, const char * const *, char *, + char **,char ***,char ** +); +extern int http_check_status( + edg_wll_Context, + char *, + char ** +); -/** - * default query timeout (in seconds) - */ -#define EDG_WLL_QUERY_TIMEOUT_DEFAULT 120 +extern int set_server_name_and_port( + edg_wll_Context, + const edg_wll_QueryRec ** +); -/** - * maximal query timeout (in seconds) - */ -#define EDG_WLL_QUERY_TIMEOUT_MAX 1800 +#endif #ifdef __cplusplus } diff --git a/org.glite.lb.client-interface/interface/context.h b/org.glite.lb.client-interface/interface/context.h index ce43cb7..e3fd725 100644 --- a/org.glite.lb.client-interface/interface/context.h +++ b/org.glite.lb.client-interface/interface/context.h @@ -14,6 +14,12 @@ extern "C" { #endif +/** + * \defgroup context Context + * + *@{ + */ + /** Opaque context type */ typedef struct _edg_wll_Context *edg_wll_Context; @@ -233,6 +239,10 @@ int edg_wll_GetLoggingJob( edg_wlc_JobId *jobid_out ); +/* + *@} end of group + */ + #ifdef __cplusplus } #endif diff --git a/org.glite.lb.client-interface/interface/events.h.T b/org.glite.lb.client-interface/interface/events.h.T index e9be675..d7787ce 100644 --- a/org.glite.lb.client-interface/interface/events.h.T +++ b/org.glite.lb.client-interface/interface/events.h.T @@ -1,10 +1,6 @@ #ifndef __EDG_WORKLOAD_LOGGING_CLIENT_EVENTS_H__ #define __EDG_WORKLOAD_LOGGING_CLIENT_EVENTS_H__ -/** - * \brief contains definition of event type codes for use both by lbapi.h and dglog.h - */ - #ident "$Header$" /* @@@AUTO @@ -22,6 +18,12 @@ extern "C" { #endif +/** + * \defgroup events Events + * \brief All L&B event types. + * + *@{ + */ /** * Predefined type for ULM string @@ -327,6 +329,9 @@ void edg_wll_FreeEvent( edg_wll_Event * event ); +/* + *@} end of group + */ #ifdef __cplusplus } diff --git a/org.glite.lb.client-interface/interface/jobstat.h.T b/org.glite.lb.client-interface/interface/jobstat.h.T index 802f119..4647f1a 100644 --- a/org.glite.lb.client-interface/interface/jobstat.h.T +++ b/org.glite.lb.client-interface/interface/jobstat.h.T @@ -17,6 +17,12 @@ extern "C" { #endif /** + * \defgroup jobstatus Job Status + * \brief Job status structure definition and related definitions. + *@{ + */ + +/** * Miscelaneous job status numeric codes */ @@ -101,8 +107,6 @@ typedef struct _edg_wll_JobStat { * \name edg_wll_JobStat manipulation */ -/*@{*/ - /** * Initialize empty status structure. * Fills in the stucture with NULL's or values with no meaning @@ -134,6 +138,10 @@ extern char *edg_wll_StatToString(edg_wll_JobStatCode); /*@}*/ +/* + *@} end of group + */ + #ifdef __cplusplus } #endif diff --git a/org.glite.lb.client-interface/interface/notification.h b/org.glite.lb.client-interface/interface/notification.h index da76527..3791f3d 100644 --- a/org.glite.lb.client-interface/interface/notification.h +++ b/org.glite.lb.client-interface/interface/notification.h @@ -13,6 +13,12 @@ extern "C" { #endif /** + * \defgroup notifications Notifications handling + * \brief Notifications handling. + *@{ + */ + +/** * default and maximal notif timeout (in seconds) */ #define EDG_WLL_NOTIF_TIMEOUT_DEFAULT 120 @@ -22,17 +28,19 @@ extern "C" { /** Register for receiving notifications. * Connects to the server specified by EDG_WLL_NOTIF_SERVER context parameter * (temporary workaround, should be resolved by registry in future). - * \param conditions: the same conditions as for \ref edg_wll_QueryJobsExt. + * \param context INOUT: context to work with + * \param conditions IN: the same conditions as for \ref edg_wll_QueryJobsExt. * currently one or more JOBID's are required. * Only a single occurence of a specific attribute is allowed * among ANDed conditions (due to the ability to modify them * further). - * \param fd = -1 create or reuse the default listening socket (one per context) + * \param fd IN: = -1 create or reuse the default listening socket (one per context) * >= 0 non-default listening socket - * \param address_override if not NULL, use this address instead of extracting it + * \param address_override IN: if not NULL, use this address instead of extracting it * from the connection (useful when multiple interfaces are present, * circumventing NAT problems etc.) - * \param valid until when the registration is valid (NULL means no interest in + * \param valid IN: until when the registration is valid (NULL means no interest in + * \param id_out OUT: returened NotifId * the value * \retval 0 OK * \retval EINVAL restrictions on conditions are not met @@ -51,10 +59,11 @@ int edg_wll_NotifNew( /** Change the receiving local address. * Report the new address to the server. * - * \param id notification ID you are binding to - * \param fd same as for \ref edg_wll_NotifNew - * \param address_override same as for \ref edg_wll_NotifNew - * \param valid same as for \ref edg_wll_NotifNew + * \param context INOUT: context to work with + * \param id IN: notification ID you are binding to + * \param fd IN; same as for \ref edg_wll_NotifNew + * \param address_override IN: same as for \ref edg_wll_NotifNew + * \param valid IN: same as for \ref edg_wll_NotifNew */ int edg_wll_NotifBind( @@ -83,7 +92,10 @@ typedef enum _edg_wll_NotifChangeOp { * of uniqueness the original conditions must have contained only a single * OR-ed row of conditions on the attributes infolved in the change. * - * \param op action to be taken on existing conditions, + * \param context INOUT: context to work with + * \param id IN: notification ID you are working with + * \param conditions IN: same as for \ref edg_wll_NotifNew + * \param op IN: action to be taken on existing conditions, * \ref edg_wll_NotifChangeOp */ int edg_wll_NotifChange( @@ -94,7 +106,9 @@ int edg_wll_NotifChange( ); /** Refresh the registration, i.e. extend its validity period. - * \param valid until when the registration is valid (NULL means no interest in + * \param context INOUT: context to work with + * \param id IN: notification ID you are working with + * \param valid IN: until when the registration is valid (NULL means no interest in * the value */ @@ -107,6 +121,8 @@ int edg_wll_NotifRefresh( /** Drop the registration. * Server is instructed not to send notifications anymore, pending ones * are discarded, listening socket is closed, and allocated memory freed. + * \param context INOUT: context to work with + * \param id IN: notification ID you are working with */ int edg_wll_NotifDrop( @@ -116,10 +132,12 @@ int edg_wll_NotifDrop( /** Receive notification. * The first incoming notification is returned. - * \param fd receive on this socket (-1 means the default for the context) - * \param timeout wait atmost this time long. (0,0) means polling, NULL waiting + * \param context INOUT: context to work with + * \param fd IN: receive on this socket (-1 means the default for the context) + * \param timeout IN: wait atmost this time long. (0,0) means polling, NULL waiting * indefinitely - * + * \param state_out OUT: returned JobStatus + * \param id_out OUT: returned NotifId * \retval 0 notification received, state_out contains the current job state * \retval EAGAIN no notification available, timeout occured */ @@ -138,6 +156,7 @@ int edg_wll_NotifReceive( * there may be some data cached so calling \ref edg_wll_NotifReceive * may return notifications immediately. * + * \param context INOUT: context to work with * \retval >=0 socket descriptor * \retval -1 error, details set in context */ @@ -149,12 +168,17 @@ int edg_wll_NotifGetFd( /** Close the default local listening socket. * Useful to force following \ref edg_wll_NotifBind to open * a new one. + * \param context INOUT: context to work with */ int edg_wll_NotifCloseFd( edg_wll_Context context ); +/* + *@} end of group + */ + #ifdef __cplusplus } #endif diff --git a/org.glite.lb.client-interface/interface/notifid.h b/org.glite.lb.client-interface/interface/notifid.h index fc52d01..8a85a50 100644 --- a/org.glite.lb.client-interface/interface/notifid.h +++ b/org.glite.lb.client-interface/interface/notifid.h @@ -7,21 +7,79 @@ extern "C" { #endif +/** + * \defgroup notifid Notification Id (NotifId) + * \brief NotifId description and handling. + *@{ + */ + /** Notification handle. * Refers to a particular registration for receiving notifications. */ typedef void *edg_wll_NotifId; -/** Parse and unparse the Id. */ -int edg_wll_NotifIdParse(const char *,edg_wll_NotifId *); -char* edg_wll_NotifIdUnparse(const edg_wll_NotifId); +/** + * Create a Job ID. + * \param server IN: notification server hostname + * \param port IN: port of the notification server + * \param notifid OUT: newly created NotifId + * \retval 0 for success + * \retval EINVAL invalid notification server + * \retval ENOMEM if memory allocation fails + */ +int edg_wll_NotifIdCreate(const char *server, int port ,edg_wll_NotifId *notifid); + +/** + * Free the NotifId structure + * \param notifid IN: for dealocation + */ +void edg_wll_NotifIdFree(edg_wll_NotifId notifid); + +/** Parse the NotifId string and creates NotifId structure + * \param notifidstr IN: string representation of NotifId + * \param notifid OUT: parsed NotifId + * \retval 0 for success + * \retval EINVAL notifidstr can't be parsed + * \retval ENOMEM if memory allocation fails + */ +int edg_wll_NotifIdParse(const char *notifidstr, edg_wll_NotifId *notifid); + +/** Unparse the NotifId (produce the string form of NotifId). + * \param notifid IN: NotifId to be converted to string + * \return allocated string which represents the NotifId + */ +char* edg_wll_NotifIdUnparse(const edg_wll_NotifId notifid); + +/** + * Extract notification server address (address:port) + * \param notifid IN: NotifId from which the address should be extracted + * \param srvName INOUT: pointer where to return server name + * \param srvPort INOUT: pointer where to return server port + */ +void edg_wll_NotifIdGetServerParts(const edg_wll_NotifId notifid, char **srvName, unsigned int *srvPort); -int edg_wll_NotifIdCreate(const char *,int,edg_wll_NotifId *); -void edg_wll_NotifIdFree(edg_wll_NotifId); +/** + * Extract unique string + * \param notifid IN: NotifId + * \retval pointer to allocated unique string representing jobid + * \retval NULL if jobid is 0 or memory allocation fails + */ +char *edg_wll_NotifIdGetUnique(const edg_wll_NotifId notifid); -void edg_wll_NotifIdGetServerParts(const edg_wll_NotifId, char **, unsigned int *); -char *edg_wll_NotifIdGetUnique(const edg_wll_NotifId); -int edg_wll_NotifIdSetUnique(edg_wll_NotifId *, const char *); +/** + * Recreate a NotifId by a new unique string + * \param unique IN: string which represent created notifid (if NULL then new + * one is created) + * \param notifid INOUT: newly created NotifId + * \retval 0 success + * \retval EINVAL invalid NotifId + * \retval ENOMEM if memory allocation fails + */ +int edg_wll_NotifIdSetUnique(edg_wll_NotifId *notifid, const char *unique); + +/* + *@} end of group + */ #ifdef __cplusplus }