Merge remote-tracking branch 'upstream/master'

Conflicts:
	configure.ac

Author: boothj5

ChangeLog

@@ -3,12 +3,12 @@
 	- Legacy SSL support
 	- Initial Android support
 	- Resolver returns all SRV records instead of one. Lookup is performed
-	  according to RFC2052.
+	  according to RFC2052
 	- xmpp_connect_raw() provides access to a xmpp_conn object just after
 	  establishing TCP connection. This allows to implement in-band
-	  registration, authentication mechanisms or serverless messaging.
+	  registration, authentication mechanisms or serverless messaging
 	- xmpp_conn_t object is reusable now and can be reconnected with saving
-	  all handlers, flags, jid and password.
+	  all handlers, flags, jid and password
 	- New API:
 		- xmpp_uuid_gen()
 		- xmpp_connect_raw()

Doxyfile

@@ -4,11 +4,19 @@ DIR=`dirname $0`
 EXPAT_PATH="$DIR/expat"
 EXPAT_FILE='lib/expat.h'
 
+echo
+echo Attention: libstrophe will be built without TLS support. To enable TLS
+echo you need to replace \'src/tls_dummy.c\' with \'src/tls_opnessl.c\' in
+echo \'jni/Android.mk\', add path to the openssl headers and link your program
+echo with libssl and libcrypto.
+echo
+
 if [ ! -d $EXPAT_PATH ]; then
     mkdir $EXPAT_PATH
 fi
 
 # TODO Accept expat tarball as argument and extract it to the right place.
+#      Or download sources from sf.net.
 
 if [ ! -d $EXPAT_PATH/lib -o ! -f "$EXPAT_PATH/$EXPAT_FILE" ]; then
     cat <<EOT

build-android.sh

@@ -533,17 +533,19 @@ int xmpp_connect_component(xmpp_conn_t * const conn, const char * const server,
 
 /** Initiate a raw connection to the XMPP server.
  *  Arguments and behaviour of the function are similar to
- *  xmpp_connect_client(), but it skips authentication process. Instead,
- *  the user's callback is called with event XMPP_CONN_RAW_CONNECT as soon
- *  as tcp connection is established.
+ *  xmpp_connect_client(), but it skips authentication process. In opposite to
+ *  xmpp_connect_client() during connection process two events are generated
+ *  instead of one. User's callback is called with event XMPP_CONN_RAW_CONNECT
+ *  when the TCP connection with the server is established. At this point user
+ *  might want to open an XMPP stream with xmpp_conn_open_stream() or establish
+ *  TLS session with xmpp_conn_tls_start(). Event XMPP_CONN_CONNECT is generated
+ *  when the XMPP stream is opened successfully and user may send stanzas over
+ *  the connection.
  *
  *  This function doesn't use password nor node part of a jid. Therefore,
  *  the only required configuration is a domain (or full jid) passed via
  *  xmpp_conn_set_jid().
  *
- *  Next step should be xmpp_conn_open_stream(). In case of legacy SSL,
- *  user might want to call xmpp_conn_tls_start() before opening the stream.
- *
  *  @see xmpp_connect_client()
  *
  *  @return XMPP_EOK (0) on success a number less than 0 on failure

src/conn.c

@@ -22,11 +22,15 @@
 typedef struct _xmpp_rand_t xmpp_rand_t;
 
 /** Create new xmpp_rand_t object.
+ *
+ *  @param ctx A Strophe context object
  *
  *  @ingroup Random
  */
 xmpp_rand_t *xmpp_rand_new(xmpp_ctx_t *ctx);
 /** Destroy an xmpp_rand_t object.
+ *
+ *  @param ctx A Strophe context object
  *
  *  @ingroup Random
  */
@@ -47,7 +51,10 @@ int xmpp_rand(xmpp_rand_t *rand);
 void xmpp_rand_bytes(xmpp_rand_t *rand, unsigned char *output, size_t len);
 
 /** Generate a nonce that is printable randomized string.
+ *  This function doesn't allocate memory and doesn't fail.
  *
+ *  @param output A buffer where a NULL-terminated string will be placed.
+ *                The string will contain len-1 printable symbols.
  *  @param len Number of bytes reserved for the output string, including
  *             end of line '\0'.
  *

src/rand.h

@@ -36,6 +36,7 @@ typedef struct resolver_srv_rr_struc {
 /** Perform lookup for RFC1035 message format.
  *  This function allocates all elements.
  *
+ *  @param ctx a Strophe context object
  *  @param buf message in RFC1035 format
  *  @param len length of the message
  *  @param srv_rr_list is the result
@@ -46,6 +47,7 @@ int resolver_srv_lookup_buf(xmpp_ctx_t *ctx, const unsigned char *buf,
                             size_t len, resolver_srv_rr_t **srv_rr_list);
 /** Resolve SRV record.
  *
+ *  @param ctx a Strophe context object
  *  @param service service of the SRV record
  *  @param proto protocol of the SRV record
  *  @param domain resolving domain
@@ -59,7 +61,8 @@ int resolver_srv_lookup(xmpp_ctx_t *ctx, const char *service, const char *proto,
 /** Release a list returned by resolver_srv_lookup() or
  *  resolver_srv_lookup_buf().
  *
+ *  @param ctx a Strophe context object
  *  @param srv_rr_list a list allocated by lookup functions
  */
 void resolver_srv_free(xmpp_ctx_t *ctx, resolver_srv_rr_t *srv_rr_list);
-#endif /* __LIBSTROPHE_RESOLVER_H__ */
+#endif /* __LIBMESODE_RESOLVER_H__ */

src/resolver.h

@@ -1101,6 +1101,7 @@ _stanza_new_with_attrs(xmpp_ctx_t *ctx, const char * const name,
 /** Create a <message/> stanza object with given attributes.
  *  Attributes are optional and may be NULL.
  *
+ *  @param ctx a Strophe context object
  *  @param type attribute 'type'
  *  @param to attribute 'to'
  *  @param id attribute 'id'
@@ -1187,6 +1188,7 @@ int xmpp_message_set_body(xmpp_stanza_t *msg, const char * const text)
 /** Create an <iq/> stanza object with given attributes.
  *  Attributes are optional and may be NULL.
  *
+ *  @param ctx a Strophe context object
  *  @param type attribute 'type'
  *  @param id attribute 'id'
  *
@@ -1201,6 +1203,8 @@ xmpp_stanza_t *xmpp_iq_new(xmpp_ctx_t *ctx, const char * const type,
 }
 
 /** Create a <presence/> stanza object.
+ *
+ *  @param ctx a Strophe context object
  *
  *  @return a new Strophe stanza object
  *

src/stanza.c

@@ -24,6 +24,7 @@
 
 /** Generate UUID version 4 in pre-allocated buffer.
  *
+ *  @param ctx a Strophe context object
  *  @param uuid pre-allocated buffer of size (XMPP_UUID_LEN + 1)
  */
 static void crypto_uuid_gen(xmpp_ctx_t *ctx, char *uuid)
@@ -56,6 +57,8 @@ static void crypto_uuid_gen(xmpp_ctx_t *ctx, char *uuid)
  *  This function allocates memory for the resulting string and must be freed
  *  with xmpp_free().
  *
+ *  @param ctx a Strophe context object
+ *
  *  @return ASCIIZ string
  */
 char *xmpp_uuid_gen(xmpp_ctx_t *ctx)