The EnableSipRegisterServer API procedure is used to specify the network address and UDP port of a SIP registrar server. Registrar servers are used to keep track of SIP enabled devices within a domain. Depending on the registrar server you use, registrar and proxy functions are often the same server entity.

If this API procedure is called, the telephony engine will immediately perform a "register transaction" using the specified registrar server. The telephony engine will then on a periodic basis, update the registrar server with current registration information.

Note also that register functions can also be used to generate SIP "Keep-alive" traffic between your application and the proxy/registrar server. "Keep-alive" traffic may be important if you deploy your applications in network environments where NAT routers and/or firewalls are present. If your application communicates with a proxy and registrar, LanScape recommends that you use REGISTER messages for session "Keep-alive" if you cannot use the normal SendSipKeepAlive(String, UInt32, Boolean, Int32) API procedure.

For additional information regarding SIP and RTP "Keep-alive" capabilities, please see the EnableKeepAliveTransmissions(Boolean, Boolean, UInt32) API procedure.

Namespace: LanScape
Assembly: LMEVoipManaged (in LMEVoipManaged.dll) Version: 6.0.5226.26700

Syntax

C#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE EnableSipRegisterServer( string NamesToRegister, bool RegisterPhoneLines, bool RegisterThroughProxy, string RegistrationServerAddress, uint RegistrationServerPort, uint RegistrationUpdateIntervalSeconds, uint RegistrationExpireTimeSeconds, uint TimeOutMs, bool RegisterNatAutoDetectEnabled )

public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE EnableSipRegisterServer(
	string NamesToRegister,
	bool RegisterPhoneLines,
	bool RegisterThroughProxy,
	string RegistrationServerAddress,
	uint RegistrationServerPort,
	uint RegistrationUpdateIntervalSeconds,
	uint RegistrationExpireTimeSeconds,
	uint TimeOutMs,
	bool RegisterNatAutoDetectEnabled
)

Visual Basic (Declaration)
Public Function EnableSipRegisterServer ( _ NamesToRegister As String, _ RegisterPhoneLines As Boolean, _ RegisterThroughProxy As Boolean, _ RegistrationServerAddress As String, _ RegistrationServerPort As UInteger, _ RegistrationUpdateIntervalSeconds As UInteger, _ RegistrationExpireTimeSeconds As UInteger, _ TimeOutMs As UInteger, _ RegisterNatAutoDetectEnabled As Boolean _ ) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE

Visual Basic (Declaration)

Public Function EnableSipRegisterServer ( _
	NamesToRegister As String, _
	RegisterPhoneLines As Boolean, _
	RegisterThroughProxy As Boolean, _
	RegistrationServerAddress As String, _
	RegistrationServerPort As UInteger, _
	RegistrationUpdateIntervalSeconds As UInteger, _
	RegistrationExpireTimeSeconds As UInteger, _
	TimeOutMs As UInteger, _
	RegisterNatAutoDetectEnabled As Boolean _
) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE

Visual C++
public: VoipMediaEngine..::.TELEPHONY_RETURN_VALUE EnableSipRegisterServer( String^ NamesToRegister, bool RegisterPhoneLines, bool RegisterThroughProxy, String^ RegistrationServerAddress, unsigned int RegistrationServerPort, unsigned int RegistrationUpdateIntervalSeconds, unsigned int RegistrationExpireTimeSeconds, unsigned int TimeOutMs, bool RegisterNatAutoDetectEnabled )

Visual C++

public:
VoipMediaEngine..::.TELEPHONY_RETURN_VALUE EnableSipRegisterServer(
	String^ NamesToRegister, 
	bool RegisterPhoneLines, 
	bool RegisterThroughProxy, 
	String^ RegistrationServerAddress, 
	unsigned int RegistrationServerPort, 
	unsigned int RegistrationUpdateIntervalSeconds, 
	unsigned int RegistrationExpireTimeSeconds, 
	unsigned int TimeOutMs, 
	bool RegisterNatAutoDetectEnabled
)

J#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE EnableSipRegisterServer( String NamesToRegister, boolean RegisterPhoneLines, boolean RegisterThroughProxy, String RegistrationServerAddress, UInt32 RegistrationServerPort, UInt32 RegistrationUpdateIntervalSeconds, UInt32 RegistrationExpireTimeSeconds, UInt32 TimeOutMs, boolean RegisterNatAutoDetectEnabled )

public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE EnableSipRegisterServer(
	String NamesToRegister,
	boolean RegisterPhoneLines,
	boolean RegisterThroughProxy,
	String RegistrationServerAddress,
	UInt32 RegistrationServerPort,
	UInt32 RegistrationUpdateIntervalSeconds,
	UInt32 RegistrationExpireTimeSeconds,
	UInt32 TimeOutMs,
	boolean RegisterNatAutoDetectEnabled
)

Parameters

NamesToRegister: Type: System..::.String
A comma separated list of names to register with the registrar server. For most applications, this would be set to the same name as what was specified for the "phone name" when the media engine was created. If your telephony application needs to be contacted using more than one "name", then specify all the names in this parameter.

RegisterPhoneLines

Type: System..::.Boolean
If set to a zero value, the registration names specified by the pNamesToRegister parameter will be assigned to the VOIP Media Engine as a whole. In this case, a received incoming call will be assigned to any available phone line.

If set to a non zero value, the registration names specified by the NamesToRegister parameter will be assigned to individual phone lines starting with phone line 0. In this case, the number of registration names specified in the "Names To Register" list must be equal to the number of configured phone lines. When incoming calls are received, the phone call will be assigned to a phone lines having the same destination name as specified in the incoming call's INVITE message. The destination user name is determined by inspecting the user name of the received INVITE message request URI header. If the request URI header user name does not exist, the user name in the "To:" header will be used to determine the call destination.

Note:
The number of user names that will actually be registered with a registrar is equal to the number of unique names specified in the "Names To Register" list. User names appearing in the "Names To Register" list will not be registered more than once in any normal registration cycle.

RegisterThroughProxy: Type: System..::.Boolean
If set to a non zero value, registration requests will be sent to your configured proxy server instead of directly to the registration server. It will then be the proxy server's responsibility to properly route the registration request to the registrar server.

RegistrationServerAddress: Type: System..::.String
The network address of the SIP registrar server. This string can be an IP address in dotted decimal format (i.e. 192.168.0.1) or a UNC network name of the device on the network.

RegistrationServerPort: Type: System..::.UInt32
The UDP port the SIP registrar sever is using for the reception of network data.

RegistrationUpdateIntervalSeconds: Type: System..::.UInt32
The registration update interval in seconds. This value defines the periodic nature of the telephony engine's registration cycles. Whenever this specified amount of time elapses, the media engine will send new registration data to the registrar server. This value is usually set to the same value as the RegistrationExpireTimeSeconds parameter. However, if you need SIP "Keep-alive" traffic between your application and the proxy/registrar servers, you can set this parameter to a smaller value. If you do not want to use REGISTER SIP messages to perform SIP "Keep-alive" functions, just set this value to the same value as the RegistrationExpireTimeSeconds parameter.

RegistrationExpireTimeSeconds: Type: System..::.UInt32
The registration expiration time in seconds. This value is sent directly to the registrar. The registrar then uses it to determine when your registration will expire. This value should never be set smaller than the RegistrationUpdateIntervalSeconds parameter value.

TimeOutMs: Type: System..::.UInt32
The time in millisecond the telephony engine will wait for a response from the registrar server. If the registrar server does not respond in this specified amount of time, an error will occur.

RegisterNatAutoDetectEnabled: Type: System..::.Boolean
Set to a non zero value to allow the media engine to determine if it is configured behind a NAT router. If you use a LanScape supplied registrar server, the media engine will be able to determine its NAT configuration. If you are using some other vendor's registrar server, the registrar server must support the ";received=x.x.x.x" parameter in SIP protocol "Via" headers.

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 VoipMediaEngine..::.TELEPHONY_RETURN_VALUE data type.

Return Value	Description
SipCallFailure	This value is returned by telephony API procedures to indicate general API failure. This error value is used as a "catch all error". If you receive this error, check to make sure that all parameters specified in the API procedure call are correct. Particularly, verify that pointers to memory regions are valid. This error return value is only used if a mapping to another specific error value does not exist. (API return value)
SipBadParameter	One of the telephony API procedures was called by application software and was passed a pointer to an invalid memory address. Normally this error will occur when application software passes NULL pointer values to the telephony API. For managed code applications, you should never see this error unless your process space has exhausted memory. (API return value)
SipInvalidHandle	Application software specified an invalid telephony handle in one of the API procedures. This usually indicates memory corruption on the part of application software. (API return value)
SipProxyNotEnabled	Indicates that an operation was attempted that requires a proxy server to be configured and enabled. However, proxy support has not yet been enabled. (API return value)
SipUnknownHost	A network address was specified as a UNC name and DNS was used to obtain the destination IP address. DNS could not resolve the UNC network name. Make sure the spelling you specified for the destination machine is correct. (API return value)
SipRegisterBadNameList	When registering individual phone lines using the EnableSipRegisterServer(String, Boolean, Boolean, String, UInt32, UInt32, UInt32, UInt32, Boolean) API procedure, this error value will be returned if the number of registration names (extensions) is not equal to the number of configured phone lines. (API return value)
SipDomainNameNotDefined	Application software has configured proxy services but has not specified a SIP domain name using the EnableSipDomain(String) API procedure. This error can be generated for the following API procedures: TransferLine(String, String, Int32, Int32), MakeCall(String, String, UInt32, Int32, Boolean, UInt32), MakeCallUri(String, Boolean, Int32, Boolean, UInt32), and EnableSipRegisterServer(String, Boolean, Boolean, String, UInt32, UInt32, UInt32, UInt32, Boolean). (API return value)
SipRegisterError	The SipRegisterError event is sent to application software when the telephony engine completes an attempt to perform a registration cycle with the configured SIP registration server and an unknown error occurred. This error does not indicate that the server could not be contacted. It indicates that the registration server received our request but responded with an error indication. (API return value, GLOBAL_NOTIFICATION)
SipRegisterTimeOut	This event indicates that the telephony engine made an attempt to contact the configured SIP registration server. The registration server however never responded to the registration request. The time out value used by the telephony engine is specified by the TimeOutMs parameter of the EnableSipRegisterServer(String, Boolean, Boolean, String, UInt32, UInt32, UInt32, UInt32, Boolean) API procedure. (API return value, GLOBAL_NOTIFICATION)
SipRegisterAuthorizationError	An application called the EnableSipRegisterServer(String, Boolean, Boolean, String, UInt32, UInt32, UInt32, UInt32, Boolean) API procedure to register with a remote registrar server. However, the registration failed because your application could not be authenticated. To allow the media engine to handle authentication requests automatically, your application should call the AddAuthorizationCredentials(String, String, String) API procedure with the proper authentication credentials prior to calling the EnableSipRegisterServer(String, Boolean, Boolean, String, UInt32, UInt32, UInt32, UInt32, Boolean) API procedure. (API return value, GLOBAL_NOTIFICATION)
SipRegisterIntervalError	When an application receives the SipRegisterIntervalError event, it indicates that the telephony engine attempted to register with the specified SIP registrar server. The server however declined the registration request because the registration time interval is not acceptable. If you receive this error, please refer to the user documentation for your SIP registration server. Note also that the EnableSipRegisterServer(String, Boolean, Boolean, String, UInt32, UInt32, UInt32, UInt32, Boolean) API procedure can also return this value immediately if a registration interval of 0 seconds was specified when the telephony engine was asked to initiate registration cycles with a SIP register server. A valid non zero registration interval must be specified to remove this error. Registration intervals are specified using a value that represents the number of second in between registration periods. The telephony engine can only verify that a non zero number of seconds has been specified for the registration period. If a registration cycle is attempted and the registration interval is unacceptable to the SIP register server, the application will also receive this error via the callback event mechanism when the registration is denied. For further information, see the EnableSipRegisterServer(String, Boolean, Boolean, String, UInt32, UInt32, UInt32, UInt32, Boolean) API procedure. (API return value, GLOBAL_NOTIFICATION)
SipThreadCreationError	The telephony engine attempted to create an internal thread object. The thread creation failed. Make sure your system has enough free resources (memory) to perform the operations you are requesting from the telephony engine. Thread creation errors are generally associated with the application process space consuming too much system memory. To resolve this error, you may want to consider disabling certain features of the media engine such as conference calling. You can also reduce memory requirements if you reduce the maximum signal length of internal media engine signal paths by specifying a smaller number for the MaxMixerLinebuffers member of the VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS structure that is passed to the StartSipTelephony(VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS) and ReStartSipTelephony(VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS) API procedures. Reducing the default stack size for threads in your application may also allow your process space to consume less system memory. (API return value, PHONE_LINE_NOTIFICATION)

Remarks

None.

Syntax

Parameters

Return Value

Remarks

See Also