Changeset 1112 for pjproject/trunk/pjmedia/include/pjmedia/transport_ice.h

Timestamp:

Mar 28, 2007 4:24:00 PM (17 years ago)

Author:

bennylp

Message:

Fixed pjnath build warnings/errors on Linux

File:

• pjproject/trunk/pjmedia/include/pjmedia/transport_ice.h (modified) (5 diffs)

pjproject/trunk/pjmedia/include/pjmedia/transport_ice.h

@@ -23 +23 @@
 /**
  * @file transport_ice.h
- * @brief Stream transport with ICE.
+ * @brief ICE capable media transport.
  */
 
@@ -31 +31 @@
 
 /**
- * @defgroup PJMEDIA_TRANSPORT_ICE ICE Socket Transport
- * @ingroup PJMEDIA_TRANSPORT_H
+ * @defgroup PJMEDIA_TRANSPORT_ICE ICE Capable media transport 
+ * @ingroup PJMEDIA_TRANSPORT
  * @brief Implementation of media transport with ICE.
  * @{
@@ -40 +40 @@
 
 
+/**
+ * Create the media transport.
+ *
+ * @param endpt         The media endpoint.
+ * @param name          Optional name to identify this ICE media transport
+ *                      for logging purposes.
+ * @param comp_cnt      Number of components to be created.
+ * @param stun_cfg      Pointer to STUN configuration settings.
+ * @param p_tp          Pointer to receive the media transport instance.
+ *
+ * @return              PJ_SUCCESS on success, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pjmedia_ice_create(pjmedia_endpt *endpt,
                                         const char *name,
@@ -45 +57 @@
                                         pj_stun_config *stun_cfg,
                                         pjmedia_transport **p_tp);
+
+/**
+ * Destroy the media transport.
+ *
+ * @param tp            The media transport.
+ *
+ * @return              PJ_SUCCESS.
+ */
 PJ_DECL(pj_status_t) pjmedia_ice_destroy(pjmedia_transport *tp);
 
+
+/**
+ * Start the initialization process of this media transport. This function
+ * will gather the transport addresses to be registered to ICE session as
+ * candidates. If STUN is configured, this will start the STUN Binding or
+ * Allocate request to get the STUN server reflexive or relayed address.
+ * This function will return immediately, and application should poll the
+ * STUN completion status by calling #pjmedia_ice_get_init_status().
+ *
+ * @param tp            The media transport.
+ * @param options       Options, see pj_ice_strans_option in PJNATH 
+ *                      documentation.
+ * @param start_addr    Local address where socket will be bound to. This
+ *                      address will be used as follows:
+ *                      - if the value is NULL, then socket will be bound
+ *                        to any available port.
+ *                      - if the value is not NULL, then if the port number
+ *                        is not zero, it will used as the starting port 
+ *                        where the socket will be bound to. If bind() to
+ *                        this port fails, this function will try to bind
+ *                        to port+2, repeatedly until it succeeded.
+ *                        If application doesn't want this function to 
+ *                        retry binding the socket to other port, it can
+ *                        specify PJ_ICE_ST_OPT_NO_PORT_RETRY option.
+ *                      - if the value is not NULL, then if the address
+ *                        is not INADDR_ANY, this function will bind the
+ *                        socket to this particular interface only, and
+ *                        no other host candidates will be added for this
+ *                        socket.
+ * @param stun_srv      Address of the STUN server, or NULL if STUN server
+ *                      reflexive mapping is not to be used.
+ * @param turn_srv      Address of the TURN server, or NULL if TURN relay
+ *                      is not to be used.
+ *
+ * @return              PJ_SUCCESS when the initialization process has started
+ *                      successfully, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pjmedia_ice_start_init(pjmedia_transport *tp,
                                             unsigned options,
@@ -52 +109 @@
                                             const pj_sockaddr_in *stun_srv,
                                             const pj_sockaddr_in *turn_srv);
+
+/**
+ * Poll the initialization status of this media transport.
+ *
+ * @param tp            The media transport.
+ *
+ * @return              PJ_SUCCESS if all candidates have been resolved
+ *                      successfully, PJ_EPENDING if transport resolution
+ *                      is still in progress, or other status on failure.
+ */
 PJ_DECL(pj_status_t) pjmedia_ice_get_init_status(pjmedia_transport *tp);
 
+
+/**
+ * Get the ICE stream transport component for the specified component ID.
+ *
+ * @param tp            The media transport.
+ * @param comp_id       The component ID.
+ * @param comp          The structure which will be filled with the
+ *                      component.
+ *
+ * @return              PJ_SUCCESS or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pjmedia_ice_get_comp(pjmedia_transport *tp,
                                           unsigned comp_id,
                                           pj_ice_strans_comp *comp);
 
+/**
+ * Initialize the ICE session.
+ *
+ * @param tp            The media transport.
+ * @param role          ICE role.
+ * @param local_ufrag   Optional local username fragment.
+ * @param local_passwd  Optional local password.
+ *
+ * @return              PJ_SUCCESS, or the appropriate error code.
+
+ */
 PJ_DECL(pj_status_t) pjmedia_ice_init_ice(pjmedia_transport *tp,
                                           pj_ice_sess_role role,
                                           const pj_str_t *local_ufrag,
                                           const pj_str_t *local_passwd);
+
+/**
+ * Modify the SDP to add ICE specific SDP attributes before sending
+ * the SDP to remote host.
+ *
+ * @param tp            The media transport.
+ * @param pool          Pool to allocate memory for the SDP elements.
+ * @param sdp           The SDP descriptor to be modified.
+ *
+ * @return              PJ_SUCCESS, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pjmedia_ice_modify_sdp(pjmedia_transport *tp,
                                             pj_pool_t *pool,
                                             pjmedia_sdp_session *sdp);
+
+/**
+ * Start ICE connectivity checks.
+ *
+ * This function will pair the local and remote candidates to create 
+ * check list. Once the check list is created and sorted based on the
+ * priority, ICE periodic checks will be started. This function will 
+ * return immediately, and application will be notified about the 
+ * connectivity check status in the callback.
+ *
+ * @param tp            The media transport.
+ * @param pool          Memory pool to parse the SDP.
+ * @param rem_sdp       The SDP received from remote agent.
+ * @param media_index   The media index (in SDP) to process.
+ *
+ * @return              PJ_SUCCESS, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pjmedia_ice_start_ice(pjmedia_transport *tp,
                                            pj_pool_t *pool,
-                                           pjmedia_sdp_session *rem_sdp,
+                                           const pjmedia_sdp_session *rem_sdp,
                                            unsigned media_index);
+
+/**
+ * Stop the ICE session (typically when the call is terminated). Application
+ * may restart the ICE session again by calling #pjmedia_ice_init_ice(),
+ * for example to use this media transport for the next call.
+ *
+ * @param tp            The media transport.
+ *
+ * @return              PJ_SUCCESS, or the appropriate error code.
+ */
 PJ_DECL(pj_status_t) pjmedia_ice_stop_ice(pjmedia_transport *tp);