Modified: qpid/proton/trunk/proton-c/include/proton/engine.h URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/engine.h?rev=1344181&r1=1344180&r2=1344181&view=diff ============================================================================== --- qpid/proton/trunk/proton-c/include/proton/engine.h (original) +++ qpid/proton/trunk/proton-c/include/proton/engine.h Wed May 30 10:14:50 2012 @@ -27,11 +27,17 @@ #include <sys/types.h> #include <proton/errors.h> +/** @file + * API for the proton Engine. + * + * @todo + */ + typedef struct pn_error_t pn_error_t; typedef struct pn_transport_t pn_transport_t; -typedef struct pn_connection_t pn_connection_t; -typedef struct pn_session_t pn_session_t; -typedef struct pn_link_t pn_link_t; +typedef struct pn_connection_t pn_connection_t; /**< Connection */ +typedef struct pn_session_t pn_session_t; /**< Session */ +typedef struct pn_link_t pn_link_t; /**< Link */ typedef struct pn_delivery_t pn_delivery_t; typedef struct pn_delivery_tag_t { @@ -41,18 +47,23 @@ typedef struct pn_delivery_tag_t { #define pn_dtag(BYTES, SIZE) ((pn_delivery_tag_t) {(SIZE), (BYTES)}) -typedef int pn_state_t; +typedef int pn_state_t; /**< encodes the state of an endpoint */ -#define PN_LOCAL_UNINIT (1) -#define PN_LOCAL_ACTIVE (2) -#define PN_LOCAL_CLOSED (4) -#define PN_REMOTE_UNINIT (8) -#define PN_REMOTE_ACTIVE (16) -#define PN_REMOTE_CLOSED (32) +#define PN_LOCAL_UNINIT (1) /**< local endpoint requires initialization */ +#define PN_LOCAL_ACTIVE (2) /**< local endpoint is active */ +#define PN_LOCAL_CLOSED (4) /**< local endpoint is closed */ +#define PN_REMOTE_UNINIT (8) /**< remote endpoint pending initialization by peer */ +#define PN_REMOTE_ACTIVE (16) /**< remote endpoint is active */ +#define PN_REMOTE_CLOSED (32) /**< remote endpoint has closed */ #define PN_LOCAL_MASK (PN_LOCAL_UNINIT | PN_LOCAL_ACTIVE | PN_LOCAL_CLOSED) #define PN_REMOTE_MASK (PN_REMOTE_UNINIT | PN_REMOTE_ACTIVE | PN_REMOTE_CLOSED) +/** @enum pn_disposition_t + * The state/outcome of a message transfer. + * + * @todo document each value + */ typedef enum pn_disposition_t { PN_RECEIVED=1, PN_ACCEPTED=2, @@ -68,25 +79,135 @@ typedef int pn_trace_t; #define PN_TRACE_FRM (2) // connection + +/** Factory to construct a new Connection. + * + * @return pointer to a new connection object. + */ pn_connection_t *pn_connection(); +/** Retrieve the state of the connection. + * + * @param[in] connection the connection + * @return the connection's state flags + */ pn_state_t pn_connection_state(pn_connection_t *connection); +/** @todo: needs documentation */ pn_error_t *pn_connection_error(pn_connection_t *connection); +/** @todo: needs documentation */ char *pn_connection_container(pn_connection_t *connection); +/** @todo: needs documentation */ void pn_connection_set_container(pn_connection_t *connection, const char *container); +/** @todo: needs documentation */ char *pn_connection_hostname(pn_connection_t *connection); +/** @todo: needs documentation */ void pn_connection_set_hostname(pn_connection_t *connection, const char *hostname); +/** Extracts the first delivery on the connection that has pending + * operations. + * + * Retrieves the first delivery on the Connection that has pending + * operations. A readable delivery indicates message data is waiting + * to be read. A writable delivery indicates that message data may be + * sent. An updated delivery indicates that the delivery's disposition + * has changed. A delivery will never be both readable and writible, + * but it may be both readable and updated or both writiable and + * updated. + * + * @param[in] connection the connection + * @return the first delivery object that needs to be serviced, else + * NULL if none + */ pn_delivery_t *pn_work_head(pn_connection_t *connection); + +/** Get the next delivery on the connection that needs has pending + * operations. + * + * @param[in] delivery the previous delivery retrieved from + * either pn_work_head() or pn_work_next() + * @return the next delivery that has pending operations, else + * NULL if none + */ pn_delivery_t *pn_work_next(pn_delivery_t *delivery); +/** Factory for creating a new session on the connection. + * + * A new session is created for the connection, and is added to the + * set of sessions maintained by the connection. + * + * @param[in] connection the session will exist over this connection + * @return pointer to new session + */ pn_session_t *pn_session(pn_connection_t *connection); + +/** Factory for creating the connection's transport. + * + * The transport used by the connection to interface with the network. + * There can only be one transport associated with a connection. + * + * @param[in] connection connection that will use the transport + * @return pointer to new session + */ pn_transport_t *pn_transport(pn_connection_t *connection); +/** Retrieve the first Session that matches the given state mask. + * + * Examines the state of each session owned by the connection, and + * returns the first Session that matches the given state mask. If + * state contains both local and remote flags, then an exact match + * against those flags is performed. If state contains only local or + * only remote flags, then a match occurs if any of the local or + * remote flags are set respectively. + * + * @param[in] connection to be searched for matching sessions + * @param[in] state mask to match + * @return the first session owned by the connection that matches the + * mask, else NULL if no sessions match + */ pn_session_t *pn_session_head(pn_connection_t *connection, pn_state_t state); + +/** Retrieve the next Session that matches the given state mask. + * + * When used with pn_session_head(), application can access all + * Sessions on the connection that match the given state. See + * pn_session_head() for description of match behavior. + * + * @param[in] session the previous session obtained from + * pn_session_head() or pn_session_next() + * @param[in] state mask to match. + * @return the next session owned by the connection that matches the + * mask, else NULL if no sessions match + */ pn_session_t *pn_session_next(pn_session_t *session, pn_state_t state); +/** Retrieve the first Link that matches the given state mask. + * + * Examines the state of each Link owned by the connection and returns + * the first Link that matches the given state mask. If state contains + * both local and remote flags, then an exact match against those + * flags is performed. If state contains only local or only remote + * flags, then a match occurs if any of the local or remote flags are + * set respectively. + * + * @param[in] connection to be searched for matching Links + * @param[in] state mask to match + * @return the first Link owned by the connection that matches the + * mask, else NULL if no Links match + */ pn_link_t *pn_link_head(pn_connection_t *connection, pn_state_t state); + +/** Retrieve the next Link that matches the given state mask. + * + * When used with pn_link_head(), the application can access all Links + * on the connection that match the given state. See pn_link_head() + * for description of match behavior. + * + * @param[in] link the previous Link obtained from pn_link_head() or + * pn_link_next() + * @param[in] state mask to match + * @return the next session owned by the connection that matches the + * mask, else NULL if no sessions match + */ pn_link_t *pn_link_next(pn_link_t *link, pn_state_t state); void pn_connection_open(pn_connection_t *connection);
Modified: qpid/proton/trunk/proton-c/include/proton/sasl.h URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-c/include/proton/sasl.h?rev=1344181&r1=1344180&r2=1344181&view=diff ============================================================================== --- qpid/proton/trunk/proton-c/include/proton/sasl.h (original) +++ qpid/proton/trunk/proton-c/include/proton/sasl.h Wed May 30 10:14:50 2012 @@ -25,40 +25,171 @@ #include <sys/types.h> #include <stdbool.h> +/** @file + * API for the SASL Secure Transport Layer. + * + * The SASL layer is responsible for establishing an authenticated + * and/or encrypted tunnel over which AMQP frames are passed between + * peers. The peer acting as the SASL Client must provide + * authentication credentials. The peer acting as the SASL Server must + * provide authentication against the received credentials. + */ + typedef struct pn_sasl_t pn_sasl_t; +/** The result of the SASL negotiation */ typedef enum { - PN_SASL_NONE=-1, - PN_SASL_OK=0, - PN_SASL_AUTH=1, - PN_SASL_SYS=2, - PN_SASL_PERM=3, - PN_SASL_TEMP=4 + PN_SASL_NONE=-1, /** negotiation not completed */ + PN_SASL_OK=0, /** authentication succeeded */ + PN_SASL_AUTH=1, /** failed due to bad credentials */ + PN_SASL_SYS=2, /** failed due to a system error */ + PN_SASL_PERM=3, /** failed due to unrecoverable error */ + PN_SASL_TEMP=4 /** failed due to transient error */ } pn_sasl_outcome_t; +/** The state of the SASL negotiation process */ typedef enum { - PN_SASL_CONF, - PN_SASL_IDLE, - PN_SASL_STEP, - PN_SASL_PASS, - PN_SASL_FAIL + PN_SASL_CONF, /** Pending configuration by application */ + PN_SASL_IDLE, /** Pending SASL Init */ + PN_SASL_STEP, /** negotiation in progress */ + PN_SASL_PASS, /** negotiation completed successfully */ + PN_SASL_FAIL /** negotiation failed */ } pn_sasl_state_t; +/** Construct an Authentication and Security Layer object + * + * @return a new SASL object representing the layer. + */ pn_sasl_t *pn_sasl(); + +/** Access the current state of the layer. + * + * @param[in] sasl the layer to retrieve the state from. + * @return The state of the sasl layer. + */ pn_sasl_state_t pn_sasl_state(pn_sasl_t *sasl); + +/** Set the acceptable SASL mechanisms for the layer. + * + * @param[in] sasl the layer to update + * @param[in] mechanisms a list of acceptable SASL mechanisms, + * separated by space + */ void pn_sasl_mechanisms(pn_sasl_t *sasl, const char *mechanisms); + +/** Retrieve the list of SASL mechanisms provided by the remote. + * + * @param[in] sasl the SASL layer. + * @return a string containing a list of the SASL mechanisms + * advertised by the remote (separated by spaces) + */ const char *pn_sasl_remote_mechanisms(pn_sasl_t *sasl); + +/** Configure the SASL layer to act as a SASL client. + * + * The role of client is similar to a TCP client - the peer requesting + * the connection. + * + * @param[in] sasl the SASL layer to configure as a client + */ void pn_sasl_client(pn_sasl_t *sasl); + +/** Configure the SASL layer to act as a server. + * + * The role of server is similar to a TCP server - the peer accepting + * the connection. + * + * @param[in] sasl the SASL layer to configure as a server + */ void pn_sasl_server(pn_sasl_t *sasl); + +/** Configure the SASL layer to use the "PLAIN" mechanism. + * + * A utility function to configure a simple client SASL layer using + * PLAIN authentication. + * + * @param[in] sasl the layer to configure. + * @param[in] username credential for the PLAIN authentication + * mechanism + * @param[in] password credential for the PLAIN authentication + * mechanism + */ void pn_sasl_plain(pn_sasl_t *sasl, const char *username, const char *password); + +/** Determine the size of the bytes available via pn_sasl_recv(). + * + * Returns the size in bytes available via pn_sasl_recv(). + * + * @param[in] sasl the SASL layer. + * @return The number of bytes available, zero if no available data. + */ size_t pn_sasl_pending(pn_sasl_t *sasl); + +/** Read challenge/response data sent from the peer. + * + * Use pn_sasl_pending to determine the size of the data. + * + * @param[in] sasl the layer to read from. + * @param[out] bytes written with up to size bytes of inbound data. + * @param[in] size maximum number of bytes that bytes can accept. + * @return The number of bytes written to bytes, or an error code if < 0. + */ ssize_t pn_sasl_recv(pn_sasl_t *sasl, char *bytes, size_t size); + +/** Send challenge or response data to the peer. + * + * @param[in] sasl The SASL layer. + * @param[in] bytes The challenge/response data. + * @param[in] size The number of data octets in bytes. + * @return The number of octets read from bytes, or an error code if < 0 + */ ssize_t pn_sasl_send(pn_sasl_t *sasl, const char *bytes, size_t size); + +/** Set the outcome of SASL negotiation + * + * Used by the server to set the result of the negotiation process. + * + * @todo + */ void pn_sasl_done(pn_sasl_t *sasl, pn_sasl_outcome_t outcome); + +/** Retrieve the outcome of SASL negotiation. + * + * @todo + */ pn_sasl_outcome_t pn_sasl_outcome(pn_sasl_t *sasl); + +/** Decode input data bytes into SASL frames, and process them. + * + * This function is called by the driver layer to pass data received + * from the remote peer into the SASL layer. + * + * @param[in] sasl the SASL layer. + * @param[in] bytes buffer of frames to process + * @param[in] available number of octets of data in 'bytes' + * @return the number of bytes consumed, or error code if < 0 + */ ssize_t pn_sasl_input(pn_sasl_t *sasl, char *bytes, size_t available); + +/** Gather output frames from the layer. + * + * This function is used by the driver to poll the SASL layer for data + * that will be sent to the remote peer. + * + * @param[in] sasl The SASL layer. + * @param[out] bytes to be filled with encoded frames. + * @param[in] size space available in bytes array. + * @return the number of octets written to bytes, or error code if < 0 + */ ssize_t pn_sasl_output(pn_sasl_t *sasl, char *bytes, size_t size); + void pn_sasl_trace(pn_sasl_t *sasl, pn_trace_t trace); + +/** Destructor for the given SASL layer. + * + * @param[in] sasl the SASL object to destroy. No longer valid on + * return. + */ void pn_sasl_destroy(pn_sasl_t *sasl); --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org
