From 0022a82e53fcaa5a874b87d1bf5d800913791513 Mon Sep 17 00:00:00 2001 From: scottmk Date: Wed, 28 Oct 2009 15:15:08 +0000 Subject: [PATCH] 1. In endElementHandler(), responding to an error: don't explain what a 401 error is unless that's the error that happened. 2. In parseWarningHandler() and parseErrorHandler(): issue messages via the usual logging routines instead of writing them to stdout and stderr. 3. Finish the doxygen-style commenting. M include/opensrf/transport_session.h M src/libopensrf/transport_session.c git-svn-id: svn://svn.open-ils.org/OpenSRF/trunk@1828 9efc2488-bf62-4759-914b-345cdb29e865 --- include/opensrf/transport_session.h | 81 ++++++++++++++--------------- src/libopensrf/transport_session.c | 56 ++++++++++---------- 2 files changed, 66 insertions(+), 71 deletions(-) diff --git a/include/opensrf/transport_session.h b/include/opensrf/transport_session.h index 824b504..4b4b921 100644 --- a/include/opensrf/transport_session.h +++ b/include/opensrf/transport_session.h @@ -5,8 +5,10 @@ @file transport_session.h @brief Header for routines to manage a connection to a Jabber server. - Manages the Jabber session. Reads data from a socket and pushes it into a SAX - parser as it arrives. When key Jabber document elements are met, logic ensues. + Manages a Jabber session. Reads messages from a socket and pushes them into a SAX parser + as they arrive, responding to various Jabber document elements as they appear. When it + sees the end of a complete message, it sends a representation of that message to the + calling code via a callback function. */ #include @@ -30,56 +32,54 @@ extern "C" { #endif +/** Note whether the login information should be sent as plaintext or as a hash digest. */ enum TRANSPORT_AUTH_TYPE { AUTH_PLAIN, AUTH_DIGEST }; struct jabber_state_machine_struct; typedef struct jabber_state_machine_struct jabber_machine; -// --------------------------------------------------------------------------------- -// Transport session. This maintains all the various parts of a session -// --------------------------------------------------------------------------------- +/** + @brief Collection of things for managing a Jabber session. +*/ struct transport_session_struct { /* our socket connection */ - socket_manager* sock_mgr; + socket_manager* sock_mgr; /**< Manages the socket to the Jabber server. */ /* our Jabber state machine */ - jabber_machine* state_machine; + jabber_machine* state_machine; /**< Keeps track of where we are in the XML. */ /* our SAX push parser context */ - xmlParserCtxtPtr parser_ctxt; + xmlParserCtxtPtr parser_ctxt; /**< Used by the XML parser. */ /* our text buffers for holding text data */ - growing_buffer* body_buffer; - growing_buffer* subject_buffer; - growing_buffer* thread_buffer; - growing_buffer* from_buffer; - growing_buffer* recipient_buffer; - growing_buffer* status_buffer; - growing_buffer* message_error_type; - growing_buffer* session_id; - int message_error_code; - - /* for OILS extenstions */ - growing_buffer* router_to_buffer; - growing_buffer* router_from_buffer; - growing_buffer* router_class_buffer; - growing_buffer* router_command_buffer; - growing_buffer* osrf_xid_buffer; - int router_broadcast; - - /* this can be anything. It will show up in the - callbacks for your convenience. Otherwise, it's - left untouched. */ - void* user_data; - - char* server; - char* unix_path; - int port; - int sock_id; - - int component; /* true if we're a component */ - - /* the Jabber message callback */ + growing_buffer* body_buffer; /**< Text of <body> of message stanza. */ + growing_buffer* subject_buffer; /**< Text of <subject> of message stanza. */ + growing_buffer* thread_buffer; /**< Text of <thread> of message stanza. */ + growing_buffer* from_buffer; /**< "from" attribute of <message>. */ + growing_buffer* recipient_buffer; /**< "to" attribute of <message>. */ + growing_buffer* status_buffer; /**< Text of <status> of message stanza. */ + growing_buffer* message_error_type; /**< "type" attribute of <error>. */ + growing_buffer* session_id; /**< "id" attribute of stream header. */ + int message_error_code; /**< "code" attribute of <error>. */ + + /* for OILS extensions */ + growing_buffer* router_to_buffer; /**< "router_to" attribute of <message>. */ + growing_buffer* router_from_buffer; /**< "router_from" attribute of <message>. */ + growing_buffer* router_class_buffer; /**< "router_class" attribute of <message>. */ + growing_buffer* router_command_buffer; /**< "router_command" attribute of <message>. */ + growing_buffer* osrf_xid_buffer; /**< "osrf_xid" attribute of <message>. */ + int router_broadcast; /**< "broadcast" attribute of <message>. */ + + void* user_data; /**< Opaque pointer from calling code. */ + + char* server; /**< address of Jabber server. */ + char* unix_path; /**< Unix pathname (if any) of socket to Jabber server */ + int port; /**< Port number of Jabber server. */ + int sock_id; /**< File descriptor of socket to Jabber. */ + + int component; /**< Boolean; true if we're a Jabber component. */ + + /** Callback from calling code, for when a complete message stanza is received. */ void (*message_callback) ( void* user_data, transport_message* msg ); //void (iq_callback) ( void* user_data, transport_iq_message* iq ); }; @@ -90,9 +90,6 @@ transport_session* init_transport( const char* server, int port, int session_wait( transport_session* session, int timeout ); -// --------------------------------------------------------------------------------- -// Sends the given Jabber message -// --------------------------------------------------------------------------------- int session_send_msg( transport_session* session, transport_message* msg ); int session_connected( transport_session* session ); diff --git a/src/libopensrf/transport_session.c b/src/libopensrf/transport_session.c index 4fa04ea..183d976 100644 --- a/src/libopensrf/transport_session.c +++ b/src/libopensrf/transport_session.c @@ -7,15 +7,16 @@ In all cases, a transport_session acts as a client with regard to Jabber. */ -#define CONNECTING_1 1 /* just starting the connection to Jabber */ -#define CONNECTING_2 2 /* First packet sent and packet received from server */ +#define CONNECTING_1 1 /**< just starting the connection to Jabber */ +#define CONNECTING_2 2 /**< XML stream opened but not yet logged in */ + /* Note. these are growing buffers, so all that's necessary is a sane starting point */ -#define JABBER_BODY_BUFSIZE 4096 -#define JABBER_SUBJECT_BUFSIZE 64 -#define JABBER_THREAD_BUFSIZE 64 -#define JABBER_JID_BUFSIZE 64 -#define JABBER_STATUS_BUFSIZE 16 +#define JABBER_BODY_BUFSIZE 4096 /**< buffer size for message body */ +#define JABBER_SUBJECT_BUFSIZE 64 /**< buffer size for message subject */ +#define JABBER_THREAD_BUFSIZE 64 /**< buffer size for message thread */ +#define JABBER_JID_BUFSIZE 64 /**< buffer size for various ids */ +#define JABBER_STATUS_BUFSIZE 16 /**< buffer size for status code */ // --------------------------------------------------------------------------------- // Jabber state machine. This is how we know where we are in the Jabber @@ -269,9 +270,12 @@ int session_connected( transport_session* session ) { before timing out. If @a timeout has a negative value other than -1, the results are not well defined. - Read all available input from the socket and pass it through grab_incoming() (a previously - designated callback function). There is no guarantee that we will get a complete message - from a single call. + Read all available input from the socket and pass it through grab_incoming() (a + callback function previously installed in the socket_manager). + + There is no guarantee that we will get a complete message from a single call. As a + result, the calling code should call this function in a loop until it gets a complete + message, or until an error occurs. */ int session_wait( transport_session* session, int timeout ) { if( ! session || ! session->sock_mgr ) { @@ -419,7 +423,8 @@ int session_connect( transport_session* session, int ss = buffer_length( session->session_id ) + strlen( password ) + 5; char hashstuff[ss]; - snprintf( hashstuff, sizeof(hashstuff), "%s%s", OSRF_BUFFER_C_STR( session->session_id ), password ); + snprintf( hashstuff, sizeof(hashstuff), "%s%s", + OSRF_BUFFER_C_STR( session->session_id ), password ); char* hash = shahash( hashstuff ); size2 = 100 + strlen( hash ); @@ -754,8 +759,11 @@ static void endElementHandler( void *session, const xmlChar *name) { if( machine->in_iq && strcmp( (const char*) name, "iq" ) == 0 ) { machine->in_iq = 0; if( ses->message_error_code > 0 ) { - osrfLogWarning( OSRF_LOG_MARK, "Error in IQ packet: code %d", ses->message_error_code ); - osrfLogWarning( OSRF_LOG_MARK, "Error 401 means not authorized" ); + if( 401 == ses->message_error_code ) + osrfLogWarning( OSRF_LOG_MARK, "Error 401 in IQ packet: not authorized" ); + else + osrfLogWarning( OSRF_LOG_MARK, "Error in IQ packet: code %d", + ses->message_error_code ); } reset_session_buffers( session ); return; @@ -861,7 +869,7 @@ static void characterHandler( } /** - @brief Report a warning from the XML parser. + @brief Log a warning from the XML parser. @param session Pointer to a transport_session, cast to a void pointer (not used). @param msg Pointer to a printf-style format string. Subsequent messages, if any, are formatted and inserted into the expanded string. @@ -869,17 +877,12 @@ static void characterHandler( The XML parser calls this function when it wants to warn about something in the XML. */ static void parseWarningHandler( void *session, const char* msg, ... ) { - - va_list args; - va_start(args, msg); - fprintf(stdout, "transport_session XML WARNING"); - vfprintf(stdout, msg, args); - va_end(args); - fprintf(stderr, "XML WARNING: %s\n", msg ); + VA_LIST_TO_STRING(msg); + osrfLogWarning( OSRF_LOG_MARK, VA_BUF ); } /** - @brief Report an error from the XML parser. + @brief Log an error from the XML parser. @param session Pointer to a transport_session, cast to a void pointer (not used). @param msg Pointer to a printf-style format string. Subsequent messages, if any, are formatted and inserted into the expanded string. @@ -887,13 +890,8 @@ static void parseWarningHandler( void *session, const char* msg, ... ) { The XML parser calls this function when it finds an error in the XML. */ static void parseErrorHandler( void *session, const char* msg, ... ){ - - va_list args; - va_start(args, msg); - fprintf(stdout, "transport_session XML ERROR"); - vfprintf(stdout, msg, args); - va_end(args); - fprintf(stderr, "XML ERROR: %s\n", msg ); + VA_LIST_TO_STRING(msg); + osrfLogError( OSRF_LOG_MARK, VA_BUF ); } /** -- 2.43.2