diff options
Diffstat (limited to 'pjlib-util/src/pjstun-client/stun_session.h')
| -rw-r--r-- | pjlib-util/src/pjstun-client/stun_session.h | 341 |
1 files changed, 323 insertions, 18 deletions
diff --git a/pjlib-util/src/pjstun-client/stun_session.h b/pjlib-util/src/pjstun-client/stun_session.h index f9759cb9..057b35aa 100644 --- a/pjlib-util/src/pjstun-client/stun_session.h +++ b/pjlib-util/src/pjstun-client/stun_session.h @@ -25,84 +25,389 @@ #include <pj/list.h> +/** Forward declaration for pj_stun_tx_data */ typedef struct pj_stun_tx_data pj_stun_tx_data; + +/** Forward declaration for pj_stun_session */ typedef struct pj_stun_session pj_stun_session; +/** + * This is the callback to be registered to pj_stun_session, to send + * outgoing message and to receive various notifications from the STUN + * session. + */ typedef struct pj_stun_session_cb { + /** + * Callback to be called by the STUN session to send outgoing message. + * + * @param tdata The STUN transmit data containing the original + * STUN message + * @param pkt Packet to be sent. + * @param pkt_size Size of the packet to be sent. + * @param addr_len Length of destination address. + * @param dst_addr The destination address. + * + * @return The callback should return the status of the + * packet sending. + */ pj_status_t (*on_send_msg)(pj_stun_tx_data *tdata, + const void *pkt, + pj_size_t pkt_size, unsigned addr_len, const pj_sockaddr_t *dst_addr); - void (*on_bind_response)(void *user_data, pj_status_t status, pj_stun_msg *response); - void (*on_allocate_response)(void *user_data, pj_status_t status, pj_stun_msg *response); - void (*on_set_active_destination_response)(void *user_data, pj_status_t status, pj_stun_msg *response); - void (*on_connect_response)(void *user_data, pj_status_t status, pj_stun_msg *response); + /** + * Callback to be called when Binding response is received or the + * transaction has timed out. + * + * @param sess The STUN session. + * @param status Status of the request. If the value if not + * PJ_SUCCESS, the transaction has timed-out + * or other error has occurred, and the response + * argument may be NULL. + * @param request The original STUN request. + * @param response The response message, on successful transaction. + */ + void (*on_bind_response)(pj_stun_session *sess, + pj_status_t status, + pj_stun_tx_data *request, + const pj_stun_msg *response); + + /** + * Callback to be called when Allocate response is received or the + * transaction has timed out. + * + * @param sess The STUN session. + * @param status Status of the request. If the value if not + * PJ_SUCCESS, the transaction has timed-out + * or other error has occurred, and the response + * argument may be NULL. + * @param request The original STUN request. + * @param response The response message, on successful transaction. + */ + void (*on_allocate_response)(pj_stun_session *sess, + pj_status_t status, + pj_stun_tx_data *request, + const pj_stun_msg *response); + + /** + * Callback to be called when Set Active Destination response is received + * or the transaction has timed out. + * + * @param sess The STUN session. + * @param status Status of the request. If the value if not + * PJ_SUCCESS, the transaction has timed-out + * or other error has occurred, and the response + * argument may be NULL. + * @param request The original STUN request. + * @param response The response message, on successful transaction. + */ + void (*on_set_active_destination_response)(pj_stun_session *sess, + pj_status_t status, + pj_stun_tx_data *request, + const pj_stun_msg *response); + + /** + * Callback to be called when Connect response is received or the + * transaction has timed out. + * + * @param sess The STUN session. + * @param status Status of the request. If the value if not + * PJ_SUCCESS, the transaction has timed-out + * or other error has occurred, and the response + * argument may be NULL. + * @param request The original STUN request. + * @param response The response message, on successful transaction. + */ + void (*on_connect_response)( pj_stun_session *sess, + pj_status_t status, + pj_stun_tx_data *request, + const pj_stun_msg *response); } pj_stun_session_cb; +/** + * This structure describe the outgoing STUN transmit data to carry the + * message to be sent. + */ struct pj_stun_tx_data { PJ_DECL_LIST_MEMBER(struct pj_stun_tx_data); - pj_pool_t *pool; - pj_stun_session *sess; - pj_stun_msg *msg; - void *user_data; + pj_pool_t *pool; /**< Pool. */ + pj_stun_session *sess; /**< The STUN session. */ + pj_stun_msg *msg; /**< The STUN message. */ + void *user_data; /**< Arbitrary user data. */ + + pj_stun_client_tsx *client_tsx; /**< Client STUN transaction. */ + pj_uint8_t client_key[12];/**< Client transaction key. */ - pj_stun_client_tsx *client_tsx; - pj_uint8_t client_key[12]; + void *pkt; /**< The STUN packet. */ + unsigned max_len; /**< Length of packet buffer. */ + unsigned pkt_size; /**< The actual length of STUN pkt. */ + + unsigned addr_len; /**< Length of destination address. */ + const pj_sockaddr_t *dst_addr; /**< Destination address. */ }; +/** + * Options that can be specified when creating or sending outgoing STUN + * messages. These options may be specified as bitmask. + */ +enum pj_stun_session_option +{ + /** + * Add short term credential to the message. This option may not be used + * together with PJ_STUN_USE_LONG_TERM_CRED option. + */ + PJ_STUN_USE_SHORT_TERM_CRED = 1, + + /** + * Add long term credential to the message. This option may not be used + * together with PJ_STUN_USE_SHORT_TERM_CRED option. + */ + PJ_STUN_USE_LONG_TERM_CRED = 2, + + /** + * Add STUN fingerprint to the message. + */ + PJ_STUN_USE_FINGERPRINT = 4 +}; + + +/** + * Create a STUN session. + * + * @param endpt The STUN endpoint, to be used to register timers etc. + * @param name Optional name to be associated with this instance. The + * name will be used for example for logging purpose. + * @param cb Session callback. + * @param p_sess Pointer to receive STUN session instance. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ PJ_DECL(pj_status_t) pj_stun_session_create(pj_stun_endpoint *endpt, const char *name, const pj_stun_session_cb *cb, pj_stun_session **p_sess); +/** + * Destroy the STUN session. + * + * @param sess The STUN session instance. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ PJ_DECL(pj_status_t) pj_stun_session_destroy(pj_stun_session *sess); +/** + * Associated an arbitrary data with this STUN session. The user data may + * be retrieved later with pj_stun_session_get_user_data() function. + * + * @param sess The STUN session instance. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ PJ_DECL(pj_status_t) pj_stun_session_set_user_data(pj_stun_session *sess, void *user_data); +/** + * Retrieve the user data previously associated to this STUN session with + * pj_stun_session_set_user_data(). + * + * @param sess The STUN session instance. + * + * @return The user data associated with this STUN session. + */ PJ_DECL(void*) pj_stun_session_get_user_data(pj_stun_session *sess); -PJ_DECL(pj_status_t) pj_stun_session_set_credential(pj_stun_session *sess, - const pj_str_t *realm, - const pj_str_t *user, - const pj_str_t *passwd); +/** + * Save a long term credential to be used by this STUN session when sending + * outgoing messages. After long term credential is configured, application + * may specify PJ_STUN_USE_LONG_TERM_CRED option when sending outgoing STUN + * message to send the long term credential in the message. + * + * @param sess The STUN session instance. + * @param realm Realm of the long term credential. + * @param user The user name. + * @param passwd The pain-text password. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) +pj_stun_session_set_long_term_credential(pj_stun_session *sess, + const pj_str_t *realm, + const pj_str_t *user, + const pj_str_t *passwd); + -PJ_DECL(pj_status_t) pj_stun_session_enable_fingerprint(pj_stun_session *sess, - pj_bool_t enabled); +/** + * Save a short term credential to be used by this STUN session when sending + * outgoing messages. After short term credential is configured, application + * may specify PJ_STUN_USE_SHORT_TERM_CRED option when sending outgoing STUN + * message to send the short term credential in the message. + * + * @param sess The STUN session instance. + * @param user The user name. + * @param passwd The pain-text password. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) +pj_stun_session_set_short_term_credential(pj_stun_session *sess, + const pj_str_t *user, + const pj_str_t *passwd); +/** + * Create a STUN Bind request message. After the message has been + * successfully created, application can send the message by calling + * pj_stun_session_send_msg(). + * + * @param sess The STUN session instance. + * @param p_tdata Pointer to receive STUN transmit data instance containing + * the request. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ PJ_DECL(pj_status_t) pj_stun_session_create_bind_req(pj_stun_session *sess, pj_stun_tx_data **p_tdata); +/** + * Create a STUN Allocate request message. After the message has been + * successfully created, application can send the message by calling + * pj_stun_session_send_msg(). + * + * @param sess The STUN session instance. + * @param p_tdata Pointer to receive STUN transmit data instance containing + * the request. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ PJ_DECL(pj_status_t) pj_stun_session_create_allocate_req(pj_stun_session *sess, pj_stun_tx_data **p_tdata); +/** + * Create a STUN Set Active Destination request message. After the message + * has been successfully created, application can send the message by calling + * pj_stun_session_send_msg(). + * + * @param sess The STUN session instance. + * @param p_tdata Pointer to receive STUN transmit data instance containing + * the request. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ PJ_DECL(pj_status_t) pj_stun_session_create_set_active_destination_req(pj_stun_session *sess, pj_stun_tx_data **p_tdata); +/** + * Create a STUN Connect request message. After the message has been + * successfully created, application can send the message by calling + * pj_stun_session_send_msg(). + * + * @param sess The STUN session instance. + * @param p_tdata Pointer to receive STUN transmit data instance containing + * the request. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ PJ_DECL(pj_status_t) pj_stun_session_create_connect_req(pj_stun_session *sess, pj_stun_tx_data **p_tdata); -PJ_DECL(pj_status_t) +/** + * Create a STUN Connection Status Indication message. After the message + * has been successfully created, application can send the message by calling + * pj_stun_session_send_msg(). + * + * @param sess The STUN session instance. + * @param p_tdata Pointer to receive STUN transmit data instance containing + * the message. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pj_stun_session_create_connection_status_ind(pj_stun_session *sess, pj_stun_tx_data **p_tdata); +/** + * Create a STUN Send Indication message. After the message has been + * successfully created, application can send the message by calling + * pj_stun_session_send_msg(). + * + * @param sess The STUN session instance. + * @param p_tdata Pointer to receive STUN transmit data instance containing + * the message. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ PJ_DECL(pj_status_t) pj_stun_session_create_send_ind(pj_stun_session *sess, pj_stun_tx_data **p_tdata); +/** + * Create a STUN Data Indication message. After the message has been + * successfully created, application can send the message by calling + * pj_stun_session_send_msg(). + * + * @param sess The STUN session instance. + * @param p_tdata Pointer to receive STUN transmit data instance containing + * the message. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ PJ_DECL(pj_status_t) pj_stun_session_create_data_ind(pj_stun_session *sess, pj_stun_tx_data **p_tdata); +/** + * Send STUN message to the specified destination. This function will encode + * the pj_stun_msg instance to a packet buffer, and add credential or + * fingerprint if necessary. If the message is a request, the session will + * also create and manage a STUN client transaction to be used to manage the + * retransmission of the request. After the message has been encoded and + * transaction is setup, the \a on_send_msg() callback of pj_stun_session_cb + * (which is registered when the STUN session is created) will be called + * to actually send the message to the wire. + * + * @param sess The STUN session instance. + * @param options Optional flags, from pj_stun_session_option. + * @param addr_len Length of destination address. + * @param dst_addr The destination socket address. + * @param tdata The STUN transmit data containing the STUN message to + * be sent. + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ PJ_DECL(pj_status_t) pj_stun_session_send_msg(pj_stun_session *sess, + unsigned options, unsigned addr_len, - const pj_sockaddr_t *server, + const pj_sockaddr_t *dst_addr, pj_stun_tx_data *tdata); +/** + * Application must call this function to notify the STUN session about + * the arrival of STUN packet. The STUN packet MUST have been checked + * first with #pj_stun_msg_check() to verify that this is indeed a valid + * STUN packet. + * + * The STUN session will decode the packet into pj_stun_msg, and process + * the message accordingly. If the message is a response, it will search + * through the outstanding STUN client transactions for a matching + * transaction ID and hand over the response to the transaction. + * + * On successful message processing, application will be notified about + * the message via one of the pj_stun_session_cb callback. + * + * @param sess The STUN session instance. + * @param packet The packet containing STUN message. + * @param pkt_size Size of the packet. + * @param parsed_len Optional pointer to receive the size of the parsed + * STUN message (useful if packet is received via a + * stream oriented protocol). + * + * @return PJ_SUCCESS on success, or the appropriate error code. + */ PJ_DECL(pj_status_t) pj_stun_session_on_rx_pkt(pj_stun_session *sess, const void *packet, pj_size_t pkt_size, |