[Opensrf-commits] r1828 - in trunk: include/opensrf src/libopensrf (scottmk)
svn at svn.open-ils.org
svn at svn.open-ils.org
Wed Oct 28 11:15:10 EDT 2009
Author: scottmk
Date: 2009-10-28 11:15:08 -0400 (Wed, 28 Oct 2009)
New Revision: 1828
Modified:
trunk/include/opensrf/transport_session.h
trunk/src/libopensrf/transport_session.c
Log:
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
Modified: trunk/include/opensrf/transport_session.h
===================================================================
--- trunk/include/opensrf/transport_session.h 2009-10-28 04:22:44 UTC (rev 1827)
+++ trunk/include/opensrf/transport_session.h 2009-10-28 15:15:08 UTC (rev 1828)
@@ -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 <opensrf/transport_message.h>
@@ -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;
+ 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 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;
+ /* 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>. */
- /* this can be anything. It will show up in the
- callbacks for your convenience. Otherwise, it's
- left untouched. */
- void* user_data;
+ void* user_data; /**< Opaque pointer from calling code. */
- char* server;
- char* unix_path;
- int port;
- int sock_id;
+ 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; /* true if we're a component */
+ int component; /**< Boolean; true if we're a Jabber component. */
- /* the Jabber message callback */
+ /** 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 @@
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 );
Modified: trunk/src/libopensrf/transport_session.c
===================================================================
--- trunk/src/libopensrf/transport_session.c 2009-10-28 04:22:44 UTC (rev 1827)
+++ trunk/src/libopensrf/transport_session.c 2009-10-28 15:15:08 UTC (rev 1828)
@@ -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 <stream> packet sent and <stream> 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 @@
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 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 @@
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 @@
}
/**
- @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 @@
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 @@
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 );
}
/**
More information about the opensrf-commits
mailing list