StartEventSubscription

 

The StartEventSubscription function can be called by application software to subscribe to an event offered by another telephony device or application.

 

Note: If you want to subscribe to events offered by another telephony device, you must call the SipTelephonyEnable API procedure prior to calling the StartEventSubscription API procedure .

 

 

TELEPHONY_RETURN_VALUE StartEventSubscription (

SIPHANDLE hStateMachine,

char *pLocalPhoneName,

char *pDestUserNameOrPhoneNumber,

char *pDestinationAddress,

int DestinationSipPort,

BOOL SubscribeThroughProxy,

char *pEventName,
char *pEventParameter,

DWORD SubscriptionIntervalSeconds,

DWORD SubscriptionResponseTimeoutMs,

DWORD SubscriptionRetryTimeoutSeconds,

EVENT_SUBSCRIBE_HANDLE *pEventSubscribeHandle

);

 

 

 

Parameters:

 

hStateMachine

[in] The handle to the telephony engine. This is the handle that was returned by a previous call to the StartSipTelephony procedure.

 

pLocalPhoneName

[in] The “Phone” name of the your media engine. This is generally set to the same phone name as what was specified when the media engine was created. Depending on the application however, you can specify any name that is appropriate. From the standpoint of the transmitted SIP SUBSCRIBE message that gets generated, the value specified here is used as the "user name" in the SIP SUBSCRIBE message's "From" header field.

 

pDestUserNameOrPhoneNumber

[in] The name of the destination telephony device offering the event.

 

pDestinationAddress

[in] The UNC network name or IP address of the device offering the event. If sip proxy support has been enabled, the parameter pDestinationAddress should be set to your sip domain name. If it is not, the configured proxy will not be used and the event subscription will be sent directly to this address.

 

DestinationSipPort

[in] The SIP port of the device offering the event. If sip proxy support has been enabled, this parameter should be set to zero unless you are subscribing to an event in which you do not want to use the configured proxy (i.e. parameter pDestinationAddress is not set to the sip domain name.

 

SubscribeThroughProxy

[in] If non zero, the event subscription request will be sent to your configured proxy server. It will be the proxy server’s responsibility to route the request to the destination.

 

pEventName

[in] The NULL terminated character string specifying the name of the event to subscribe to.

 

pEventParameter

[in] A NULL terminated character string that specifies whatever generic parameter string your application requires. This event parameter string is appended to the transmitted SUBSCRIBE SIP message "Event:" header.

 

SubscriptionIntervalSeconds

[in] The number of seconds the event subscription will persist.

 

SubscriptionResponseTimeoutMs

[in] The time in Ms to wait for the far end to respond to the subscription request.

 

SubscriptionRetryTimeoutSeconds

[in] The time in Ms to wait before retrying a failed subscription request.

 

pEventSubscribeHandle

[out] The returned subscription handle. An application should save this handle in order to terminate the event subscription.

 

 

 

 

Return Value:

 

If the function succeeds, the return value will be SipSuccess.

 

If the function fails, the return value will be one of the following values as specified by the TELEPHONY_RETURN_VALUE data type.

 

 

 

Value

Description

SipInvalidHandle

An API procedure was passed an invalid handle. The telephony engine attempts to verify user specified telephony handles and returns this error when an invalid handle is detected.

 

SipSubscriptionAlreadyExists

The specified event subscription already exists.

 

SipBadParameter

For API procedures that receive pointers from user software, this error indicates that a NULL pointer condition was detected. Make sure all pointers your software passes to the telephony API are valid.

 

SipProxyNotEnabled

The SubscribeThroughProxy parameter was set to a non zero value. However, sip proxy support has not been enabled. Make sure sip proxy support is enabled before attempting the event subscription.

 

SipMemoryError

Indicates a critical internal memory error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application.

 

SipEventError

Indicates a critical internal error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application. This error indicates the operating system can not create additional event handles. Close all other non essential applications.

 

SipDomainNameNotDefined

A telephony operation was specified that requires a SIP domain name to be defined. Call the EnableSipDomain API procedure before attempting this operation.

 

SipUnknownHost

The telephony engine failed to resolve the IP address of another machine that was specified by a UNC network name. This error predominately occurs when the specified name of the target machine is spelled incorrectly. How IP addresses are resolved depends on your network configuration. Normally DNS is recommended for IP address resolution. Other possibilities are WINS name resolution or NetBios. Make sure your network is properly configured for name resolution.

 

SipThreadCreationError

Indicates a critical thread creation error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application. This error indicates the operating system can not create additional threads of execution. Close all other non essential applications.