@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>
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 );
};
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 );
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
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 ) {
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 );
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;
}
/**
- @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.
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.
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 );
}
/**
projects / opensrf-equinox.git / commitdiff