Changeset 4608 for pjproject/branches/projects/pjsua2/pjsip/include/pjsua2/endpoint.hpp

Timestamp:

Oct 1, 2013 9:41:01 AM (11 years ago)

Author:

bennylp

Message:

Re #1519:

• Account API (prototype)
• Account config implementation
• Refactoring in types, endpoint, etc for better consistency
• Should compile ok with make but not running yet

File:

• pjproject/branches/projects/pjsua2/pjsip/include/pjsua2/endpoint.hpp (modified) (6 diffs)

pjproject/branches/projects/pjsua2/pjsip/include/pjsua2/endpoint.hpp

@@ -40 +40 @@
 
 
+//////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Argument to EpCallback::onNatDetectionComplete() callback.
+ */
+struct OnNatDetectionCompleteParam
+{
+    /**
+     * Status of the detection process. If this value is not PJ_SUCCESS,
+     * the detection has failed and \a nat_type field will contain
+     * PJ_STUN_NAT_TYPE_UNKNOWN.
+     */
+    pj_status_t         status;
+
+    /**
+     * The text describing the status, if the status is not PJ_SUCCESS.
+     */
+    string              reason;
+
+    /**
+     * This contains the NAT type as detected by the detection procedure.
+     * This value is only valid when the \a status is PJ_SUCCESS.
+     */
+    pj_stun_nat_type    natType;
+
+    /**
+     * Text describing that NAT type.
+     */
+    string              natTypeName;
+
+};
+
+/**
+ * Argument to EpCallback::onNatCheckStunServersComplete() callback.
+ */
+struct OnNatCheckStunServersCompleteParam
+{
+    /**
+     * Arbitrary user data that was passed to Endpoint::natCheckStunServers()
+     * function.
+     */
+    Token               userData;
+
+    /**
+     * This will contain PJ_SUCCESS if at least one usable STUN server
+     * is found, otherwise it will contain the last error code during
+     * the operation.
+     */
+    pj_status_t         status;
+
+    /**
+     * The server name that yields successful result. This will only
+     * contain value if status is successful.
+     */
+    string              name;
+
+    /**
+     * The server IP address and port in "IP:port" format. This will only
+     * contain value if status is successful.
+     */
+    SocketAddress       addr;
+};
+
+/**
+ * Parameter of EpCallback::OnTimer() callback.
+ */
+struct OnTimerParam
+{
+    /**
+     * Arbitrary user data that was passed to Endpoint::utilTimerSchedule()
+     * function.
+     */
+    Token               userData;
+
+    /**
+     * The interval of this timer, in miliseconds.
+     */
+    unsigned            msecDelay;
+};
+
+/**
+ * Parameter of EpCallback::onTransportState() callback.
+ */
+struct OnTransportStateParam
+{
+    /**
+     * The transport handle.
+     */
+    TransportHandle     hnd;
+
+    /**
+     * Transport current state.
+     */
+    pjsip_transport_state state;
+
+    /**
+     * The last error code related to the transport state.
+     */
+    pj_status_t         lastError;
+};
+
+/**
+ * Parameter of EpCallback::onSelectAccount() callback.
+ */
+struct OnSelectAccountParam
+{
+    /**
+     * The incoming request.
+     */
+    SipRxData           rdata;
+
+    /**
+     * The account index to be used to handle the request.
+     * Upon entry, this will be filled by the account index
+     * chosen by the library. Application may change it to
+     * another value to use another account.
+     */
+    int                 accountIndex;
+};
+
+//////////////////////////////////////////////////////////////////////////////
+
 /**
  * Interface for receiving callbacks from the library. Application inherits
@@ -58 +180 @@
      */
     virtual void onNatDetectionComplete(
-                        const NatDetectionCompleteParam &prm)
+                        const OnNatDetectionCompleteParam &prm)
     {}
 
@@ -68 +190 @@
      */
     virtual void onNatCheckStunServersComplete(
-                        const NatCheckStunServersCompleteParam &prm)
+                        const OnNatCheckStunServersCompleteParam &prm)
     {}
 
@@ -76 +198 @@
      * @param prm       Callback parameters.
      */
-    virtual void onTransportStateChanged(
-                        const TransportStateChangedParam &prm)
+    virtual void onTransportState(
+                        const OnTransportStateParam &prm)
     {}
 
@@ -86 +208 @@
      * @param prm       Callback parameters.
      */
-    virtual void OnTimerComplete(const TimerCompleteParam &prm)
+    virtual void onTimer(const OnTimerParam &prm)
     {}
-};
+
+    /**
+     * This callback can be used by application to override the account
+     * to be used to handle an incoming message. Initially, the account to
+     * be used will be calculated automatically by the library. This initial
+     * account will be used if application does not implement this callback,
+     * or application sets an invalid account upon returning from this
+     * callback.
+     *
+     * Note that currently the incoming messages requiring account assignment
+     * are INVITE, MESSAGE, SUBSCRIBE, and unsolicited NOTIFY. This callback
+     * may be called before the callback of the SIP event itself, i.e:
+     * incoming call, pager, subscription, or unsolicited-event.
+     *
+     * @param prm       Callback parameters.
+     */
+    virtual void onSelectAccount(OnSelectAccountParam &prm)
+    {}
+};
+
+
+//////////////////////////////////////////////////////////////////////////////
+
+struct UaConfig
+{
+    /**
+     * Maximum calls to support (default: 4). The value specified here
+     * must be smaller than the compile time maximum settings
+     * PJSUA_MAX_CALLS, which by default is 32. To increase this
+     * limit, the library must be recompiled with new PJSUA_MAX_CALLS
+     * value.
+     */
+    unsigned            maxCalls;
+
+    /**
+     * Number of worker threads. Normally application will want to have at
+     * least one worker thread, unless when it wants to poll the library
+     * periodically, which in this case the worker thread can be set to
+     * zero.
+     */
+    unsigned            threadCnt;
+
+    /**
+     * Array of nameservers to be used by the SIP resolver subsystem.
+     * The order of the name server specifies the priority (first name
+     * server will be used first, unless it is not reachable).
+     */
+    StringVector        nameserver;
+
+    /**
+     * Optional user agent string (default empty). If it's empty, no
+     * User-Agent header will be sent with outgoing requests.
+     */
+    string              userAgent;
+
+    /**
+     * Array of STUN servers to try. The library will try to resolve and
+     * contact each of the STUN server entry until it finds one that is
+     * usable. Each entry may be a domain name, host name, IP address, and
+     * it may contain an optional port number. For example:
+     *  - "pjsip.org" (domain name)
+     *  - "sip.pjsip.org" (host name)
+     *  - "pjsip.org:33478" (domain name and a non-standard port number)
+     *  - "10.0.0.1:3478" (IP address and port number)
+     *
+     * When nameserver is configured in the \a pjsua_config.nameserver field,
+     * if entry is not an IP address, it will be resolved with DNS SRV
+     * resolution first, and it will fallback to use DNS A resolution if this
+     * fails. Port number may be specified even if the entry is a domain name,
+     * in case the DNS SRV resolution should fallback to a non-standard port.
+     *
+     * When nameserver is not configured, entries will be resolved with
+     * #pj_gethostbyname() if it's not an IP address. Port number may be
+     * specified if the server is not listening in standard STUN port.
+     */
+    StringVector        stunServer;
+
+    /**
+     * This specifies if the library startup should ignore failure with the
+     * STUN servers. If this is set to PJ_FALSE, the library will refuse to
+     * start if it fails to resolve or contact any of the STUN servers.
+     *
+     * Default: TRUE
+     */
+    bool                stunIgnoreFailure;
+
+    /**
+     * Support for adding and parsing NAT type in the SDP to assist
+     * troubleshooting. The valid values are:
+     *  - 0: no information will be added in SDP, and parsing is disabled.
+     *  - 1: only the NAT type number is added.
+     *  - 2: add both NAT type number and name.
+     *
+     * Default: 1
+     */
+    int                 natTypeInSdp;
+
+    /**
+     * Handle unsolicited NOTIFY requests containing message waiting
+     * indication (MWI) info. Unsolicited MWI is incoming NOTIFY requests
+     * which are not requested by client with SUBSCRIBE request.
+     *
+     * If this is enabled, the library will respond 200/OK to the NOTIFY
+     * request and forward the request to EpCallback.onMwiInfo() callback.
+     *
+     * See also AccountMwiConfig.enabled.
+     *
+     * Default: PJ_TRUE
+     */
+    bool                mwiUnsolicitedEnabled;
+
+public:
+    /**
+     * Default constructor to initialize with default values.
+     */
+    UaConfig();
+
+    /**
+     * Construct from pjsua_config.
+     */
+    void fromPj(const pjsua_config &ua_cfg);
+
+    /**
+     * Export to pjsua_config
+     */
+    pjsua_config toPj() const;
+};
+
+
+/**
+ * Data containing log entry to be written by the LogWriter.
+ */
+struct LogEntry
+{
+    /** Log verbosity level of this message */
+    int         level;
+
+    /** The log message */
+    string      msg;
+
+    /** ID of current thread */
+    long        threadId;
+
+    /** The name of the thread that writes this log */
+    string      threadName;
+};
+
+
+/**
+ * Interface for writing log messages. Applications can inherit this class
+ * and supply it in the LogConfig structure to implement custom log
+ * writing facility.
+ */
+class LogWriter
+{
+public:
+    /** Destructor */
+    virtual ~LogWriter() {}
+
+    /** Write a log entry. */
+    virtual void write(const LogEntry &entry) = 0;
+};
+
+
+/**
+ * Logging configuration, which can be (optionally) specified when calling
+ * Lib::init().
+ */
+struct LogConfig
+{
+    /** Log incoming and outgoing SIP message? Yes!  */
+    unsigned            msgLogging;
+
+    /** Input verbosity level. Value 5 is reasonable. */
+    unsigned            level;
+
+    /** Verbosity level for console. Value 4 is reasonable. */
+    unsigned            consoleLevel;
+
+    /** Log decoration. */
+    unsigned            decor;
+
+    /** Optional log filename if app wishes the library to write to log file.
+     */
+    string              filename;
+
+    /**
+     * Additional flags to be given to #pj_file_open() when opening
+     * the log file. By default, the flag is PJ_O_WRONLY. Application
+     * may set PJ_O_APPEND here so that logs are appended to existing
+     * file instead of overwriting it.
+     *
+     * Default is 0.
+     */
+    unsigned            fileFlags;
+
+    /**
+     * Custom log writer, if required. If specified, the instance of LogWriter
+     * must be kept alive througout the duration of the application.
+     */
+    LogWriter           *writer;
+
+public:
+    /** Default constructor initialises with default values */
+    LogConfig();
+
+    /** Construct from pjsua_logging_config */
+    void fromPj(const pjsua_logging_config &lc);
+
+    /** Generate pjsua_logging_config. */
+    pjsua_logging_config toPj() const;
+};
+
+
+/**
+ * This structure describes media configuration, which will be specified
+ * when calling Lib::init().
+ */
+struct MediaConfig
+{
+public:
+    /**
+     * Clock rate to be applied to the conference bridge.
+     * If value is zero, default clock rate will be used
+     * (PJSUA_DEFAULT_CLOCK_RATE, which by default is 16KHz).
+     */
+    unsigned            clockRate;
+
+    /**
+     * Clock rate to be applied when opening the sound device.
+     * If value is zero, conference bridge clock rate will be used.
+     */
+    unsigned            sndClockRate;
+
+    /**
+     * Channel count be applied when opening the sound device and
+     * conference bridge.
+     */
+    unsigned            channelCount;
+
+    /**
+     * Specify audio frame ptime. The value here will affect the
+     * samples per frame of both the sound device and the conference
+     * bridge. Specifying lower ptime will normally reduce the
+     * latency.
+     *
+     * Default value: PJSUA_DEFAULT_AUDIO_FRAME_PTIME
+     */
+    unsigned            audioFramePtime;
+
+    /**
+     * Specify maximum number of media ports to be created in the
+     * conference bridge. Since all media terminate in the bridge
+     * (calls, file player, file recorder, etc), the value must be
+     * large enough to support all of them. However, the larger
+     * the value, the more computations are performed.
+     *
+     * Default value: PJSUA_MAX_CONF_PORTS
+     */
+    unsigned            maxMediaPorts;
+
+    /**
+     * Specify whether the media manager should manage its own
+     * ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created
+     * and at least one worker thread will be created too. If no,
+     * the RTP/RTCP sockets will share the same ioqueue as SIP sockets,
+     * and no worker thread is needed.
+     *
+     * Normally application would say yes here, unless it wants to
+     * run everything from a single thread.
+     */
+    bool                hasIoqueue;
+
+    /**
+     * Specify the number of worker threads to handle incoming RTP
+     * packets. A value of one is recommended for most applications.
+     */
+    unsigned            threadCnt;
+
+    /**
+     * Media quality, 0-10, according to this table:
+     *   5-10: resampling use large filter,
+     *   3-4:  resampling use small filter,
+     *   1-2:  resampling use linear.
+     * The media quality also sets speex codec quality/complexity to the
+     * number.
+     *
+     * Default: 5 (PJSUA_DEFAULT_CODEC_QUALITY).
+     */
+    unsigned            quality;
+
+    /**
+     * Specify default codec ptime.
+     *
+     * Default: 0 (codec specific)
+     */
+    unsigned            ptime;
+
+    /**
+     * Disable VAD?
+     *
+     * Default: 0 (no (meaning VAD is enabled))
+     */
+    bool                noVad;
+
+    /**
+     * iLBC mode (20 or 30).
+     *
+     * Default: 30 (PJSUA_DEFAULT_ILBC_MODE)
+     */
+    unsigned            ilbcMode;
+
+    /**
+     * Percentage of RTP packet to drop in TX direction
+     * (to simulate packet lost).
+     *
+     * Default: 0
+     */
+    unsigned            txDropPct;
+
+    /**
+     * Percentage of RTP packet to drop in RX direction
+     * (to simulate packet lost).
+     *
+     * Default: 0
+     */
+    unsigned            rxDropPct;
+
+    /**
+     * Echo canceller options (see #pjmedia_echo_create())
+     *
+     * Default: 0.
+     */
+    unsigned            ecOptions;
+
+    /**
+     * Echo canceller tail length, in miliseconds. Setting this to zero
+     * will disable echo cancellation.
+     *
+     * Default: PJSUA_DEFAULT_EC_TAIL_LEN
+     */
+    unsigned            ecTailLen;
+
+    /**
+     * Audio capture buffer length, in milliseconds.
+     *
+     * Default: PJMEDIA_SND_DEFAULT_REC_LATENCY
+     */
+    unsigned            sndRecLatency;
+
+    /**
+     * Audio playback buffer length, in milliseconds.
+     *
+     * Default: PJMEDIA_SND_DEFAULT_PLAY_LATENCY
+     */
+    unsigned            sndPlayLatency;
+
+    /**
+     * Jitter buffer initial prefetch delay in msec. The value must be
+     * between jb_min_pre and jb_max_pre below.
+     *
+     * Default: -1 (to use default stream settings, currently 150 msec)
+     */
+    int                 jbInit;
+
+    /**
+     * Jitter buffer minimum prefetch delay in msec.
+     *
+     * Default: -1 (to use default stream settings, currently 60 msec)
+     */
+    int                 jbMinPre;
+
+    /**
+     * Jitter buffer maximum prefetch delay in msec.
+     *
+     * Default: -1 (to use default stream settings, currently 240 msec)
+     */
+    int                 jbMaxPre;
+
+    /**
+     * Set maximum delay that can be accomodated by the jitter buffer msec.
+     *
+     * Default: -1 (to use default stream settings, currently 360 msec)
+     */
+    int                 jbMax;
+
+    /**
+     * Specify idle time of sound device before it is automatically closed,
+     * in seconds. Use value -1 to disable the auto-close feature of sound
+     * device
+     *
+     * Default : 1
+     */
+    int                 sndAutoCloseTime;
+
+    /**
+     * Specify whether built-in/native preview should be used if available.
+     * In some systems, video input devices have built-in capability to show
+     * preview window of the device. Using this built-in preview is preferable
+     * as it consumes less CPU power. If built-in preview is not available,
+     * the library will perform software rendering of the input. If this
+     * field is set to PJ_FALSE, software preview will always be used.
+     *
+     * Default: PJ_TRUE
+     */
+    bool                vidPreviewEnableNative;
+
+public:
+    /** Default constructor initialises with default values */
+    MediaConfig();
+
+    /** Construct from pjsua_media_config. */
+    void fromPj(const pjsua_media_config &mc);
+
+    /** Export */
+    pjsua_media_config toPj() const;
+};
+
+
+/**
+ * Endpoint configuration
+ */
+struct EpConfig
+{
+    /** UA config */
+    UaConfig            uaConfig;
+
+    /** Logging config */
+    LogConfig           logConfig;
+
+    /** Media config */
+    MediaConfig         medConfig;
+};
+
+//////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -214 +770 @@
     /**
      * Schedule a timer with the specified interval and user data. When the
-     * interval elapsed, EpCallback::OnTimerComplete() callback will be
+     * interval elapsed, EpCallback::OnTimer() callback will be
      * called. Note that the callback may be executed by different thread,
      * depending on whether worker thread is enabled or not.