sipxtapi.h

基于sipfoundy 公司开发的sipx协议API

 */
SIPXTAPI_API SIPX_RESULT sipxConferenceGetCalls(const SIPX_CONF hConf,
                                                SIPX_CALL calls[], 
                                                const size_t iMax, 
                                                size_t& nActual) ;

/**
 * Puts conference members on hold.  Either a bridging conference hold
 * (conference members can talk to each other while on hold), or
 * a non-bridging conference hold (conference members cannot talk to 
 * anyone while on hold).
 *
 * @param hConf Handle to a conference.  Conference handles are obtained 
 *        by invoking sipxConferenceCreate.
 * @param bBridging true for a bridging conference hold,
 *        false for a non-bridging conference hold.
 */
SIPXTAPI_API SIPX_RESULT sipxConferenceHold(const SIPX_CONF hConf,
                                            bool bBridging = true);
                                            
/**
 * Removes conference members from a held state.
 *
 * @deprecated Still under development
 *
 * @param hConf Handle to a conference.  Conference handles are obtained 
 *        by invoking sipxConferenceCreate.
 */
SIPXTAPI_API SIPX_RESULT sipxConferenceUnhold(const SIPX_CONF hConf);

/**
 * Destroys a conference.  All participants within a conference are
 * dropped. 
 *
 * @param hConf Handle to a conference.  Conference handles are obtained 
 *        by invoking sipxConferenceCreate.
 */ 
SIPXTAPI_API SIPX_RESULT sipxConferenceDestroy(SIPX_CONF hConf) ;

/**
 * Set a media property on the media interface associated with the given conference.  
 * The property names may be media subsystem specific.  This may be used to set 
 * conference/media interface specific properties.  This interface is for media 
 * interface implementations that support having seperate device, audio, video or other
 * media properties for each conference or simple 2-way call.  The functions such  as
 * sipxAudioSetCallInputDevice, sipxAudioSetRingerOutputDevice, sipxAudioEnableSpeaker,
 * sipxAudioMute set media properties for the global media device for a sipX instance.
 * On media implementations that support the concept of a media device for each conference
 * or simple 2-way call sipxConferenceSetMediaProperty may be used.
 * 
 * Note: the application should be aware of when the media interfaces is created.  For
 * a conference, the media interface is not created until the first call is joined or
 * added.
 *
 * Media interfaces that wish to interoperate should implement the following properties
 * and values:
 *
 * Property Name                  Property Values
 * =======================        ===============
 * "audioInput1.muteState"        "true", "false" for systems that may have a microphone for each conference or 2-way call
 * "audioInput1.device"           same value as szDevice in sipxAudioSetCallInputDevice
 * "audioOutput1.deviceType"      "speaker", "ringer" same as sipxAudioEnableSpeaker, but for specific conference or 2-way call
 * "audioOutput1.ringerDevice"    same value as szDevice in sipxAudioSetRingerOutputDevice 
 * "audioOutput1.speakerDevice"   same values as szDevice in sipxAudioSetCallOutputDevice
 * "audioOutput1.volume"          string value of iLevel in sipxAudioSetVolume
 *
 * @param hConf Handle to a conference (and implied assocated media interface).
 * @param szPropertyName name of the media interface specific property to set.
 * @param szPropertyValue new value to set on the media interface specific property.
 */
SIPXTAPI_API SIPX_RESULT sipxConferenceSetMediaProperty(const SIPX_CONF hConf,
                                                        const char* szPropertyName,
                                                        const char* szPropertyValue);
//@}

/** @name Audio Methods */
//@{

/**
 * Set the local microphone gain.  If the microphone is muted, 
 * resetting the gain will not enable audio -- you must unmute
 * the microphone.
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param iLevel The level of the local microphone gain
 */
SIPXTAPI_API SIPX_RESULT sipxAudioSetGain(const SIPX_INST hInst,
                                          const int iLevel) ;


/**
 * Get the current microphone gain.
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param iLevel The level of the gain of the microphone
 */
SIPXTAPI_API SIPX_RESULT sipxAudioGetGain(const SIPX_INST hInst,
                                          int& iLevel) ;


/**
 * Mute or unmute the global microphone.  For media implementation that 
 * have only a single microphone active at one time, this sets the mute state
 * of the microphone.  For devices that may a microphone assocated with  each
 * conference or simple 2-way call see: sipxConferenceSetMediaProperty
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param bMute True if the microphone is to be muted and false if it 
 *        is not to be muted
 */
SIPXTAPI_API SIPX_RESULT sipxAudioMute(const SIPX_INST hInst,
                                       const bool bMute) ;


/**
 * Gets the mute state of the global microphone.  For media implementations that 
 * have only a single microphone active at one time, this gets the mute state
 * of the microphone.  For devices that may have a microphone associated with  
 * each conference or simple 2-way call, see: sipxConferenceGetMediaProperty
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param bMuted True if the microphone has been muted and false if it 
 *        is not mute
 */
SIPXTAPI_API SIPX_RESULT sipxAudioIsMuted(const SIPX_INST hInst,
                                          bool &bMuted) ;


/**
 * Enables one of the speakers on the global output.  For media implementations that
 * have only a single active speaker output active at one time, this enables the
 * given speaker type.  For devices that may have a speaker output active for each
 * conference or simple 2-way call see: sipxConferenceSetMediaProperty
 * 
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param type The type of the speaker either the logical ringer 
 *		  (used to alert user of in inbound call) or speaker 
 *        (in call audio device).
 */
SIPXTAPI_API SIPX_RESULT sipxAudioEnableSpeaker(const SIPX_INST hInst,
                                                const SPEAKER_TYPE type) ;


/**
 * Gets the enabled speaker selection on the global output.
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param type The type of the speaker either the logical ringer 
 *	      (used to alert user of in inbound call) or speaker 
 *        (in call audio device).
 */
SIPXTAPI_API SIPX_RESULT sipxAudioGetEnabledSpeaker(const SIPX_INST hInst,
                                                    SPEAKER_TYPE& type) ;


/**
 * Sets the audio level for the designated global speaker type.  If the speaker type
 * is enabled, the change it audio will be heard instantly.  If the media implementation
 * supports a audio output for each conference or 2-way call, the application should
 * use sipxConferenceSetMediaProperty.
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param type The type of the speaker either the logical ringer 
 *	      (used to alert user of in inbound call) or speaker 
 *        (in call audio device).
 * @param iLevel The level of the gain of the microphone
 */
SIPXTAPI_API SIPX_RESULT sipxAudioSetVolume(const SIPX_INST hInst,
                                            const SPEAKER_TYPE type, 
                                            const int iLevel) ;


/**
 * Gets the audio level for the designated global speaker type
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param type The type of the speaker either the logical ringer 
 *		  (used to alert user of in inbound call) or speaker 
 *        (in call audio device).
 * @param iLevel The level of the gain of the microphone
 */
SIPXTAPI_API SIPX_RESULT sipxAudioGetVolume(const SIPX_INST hInst,
                                            const SPEAKER_TYPE type, 
                                            int& iLevel) ;


/**
 * Enables or disables Acoustic Echo Cancellation (AEC).
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param enable True if AEC is to be enabled and false if 
 *        AEC is to be disabled.
 */
SIPXTAPI_API SIPX_RESULT sipxAudioEnableAEC(const SIPX_INST hInst,
                                            const bool enable) ;


/**
 * Gets the enabled or disabled state of Acoustic Echo Cancellation (AEC).
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param enabled True if AEC is enabled and false if AEC is disabled.
 */
SIPXTAPI_API SIPX_RESULT sipxAudioIsAECEnabled(const SIPX_INST hInst,
                                               bool& enabled) ;
 
/**
 * Get the number of input devices available on this system.
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param numDevices The number of input devices available
 *        on this system. 
 */
SIPXTAPI_API SIPX_RESULT sipxAudioGetNumInputDevices(const SIPX_INST hInst,
                                                     size_t& numDevices) ;

/**
 * Get the name/identifier for input device at position index
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param index Zero based index of the input device to be queried.
 * @param szDevice Reference an character string pointer to receive 
 *                 the device name.
 */
SIPXTAPI_API SIPX_RESULT sipxAudioGetInputDevice(const SIPX_INST hInst,
                                                 const int index,
                                                 const char*& szDevice) ;

/**
 * Get the number of output devices available on this system
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param numDevices The number of output devices available
 *        on this system. 
 */
SIPXTAPI_API SIPX_RESULT sipxAudioGetNumOutputDevices(const SIPX_INST hInst,
                                                      size_t& numDevices) ;

/**
 * Get the name/identifier for output device at position index
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param index Zero based index of the output device to be queried.
 * @param szDevice Reference an character string pointer to receive 
 *                 the device name.
 */
SIPXTAPI_API SIPX_RESULT sipxAudioGetOutputDevice(const SIPX_INST hInst,
                                                  const int index,
                                                  const char*& szDevice) ;


/**
 * Get the Active name/identifier for global output device.  For media
 * implementations that support an output device for each conference or
 * or two way call see: sipxConferenceSetMediaProperty
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param szDevice Reference an character string pointer to receive 
 *                 the device name.
 */
SIPXTAPI_API SIPX_RESULT sipxAudioGetActiveOutputDevice(const SIPX_INST hInst,                                                 
                                                        char* szDevice) ;


/**
 * Set the global input device (in-call microphone).  
 *
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param szDevice Character string pointer to be set to
 *                 a string name of the output device. 
 */
SIPXTAPI_API SIPX_RESULT sipxAudioSetCallInputDevice(const SIPX_INST hInst,
                                                     const char* szDevice) ;

/**
 * Set the global ringer/alerting device.
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param szDevice The call ringer/alerting device.
 */
SIPXTAPI_API SIPX_RESULT sipxAudioSetRingerOutputDevice(const SIPX_INST hInst,
                                                        const char* szDevice) ;


/**
 * Set the global output device (in-call speaker).
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param szDevice The call output device.
 */
SIPXTAPI_API SIPX_RESULT sipxAudioSetCallOutputDevice(const SIPX_INST hInst,
                                                      const char* szDevice) ;


/** VIDEO: Add Video config stuff here */

//@}
/** @name Line / Identity Methods*/
//@{


/**
 * Adds a line appearance.  A line appearance defines your address of record
 * and is used both as your "From" caller-id and as the public identity to 
 * which you will receive calls for.  Directing calls to a particular user 
 * agent is achieved using registrations.
 * 
 * @param hInst Instance pointer obtained by sipxInitialize.
 * @param szLineURL The address of record for the line identity.  Can be 
 *        prepended with a Display Name.
 *        e.g