The InitializeMediaEngine function allows you to initialize the telephony engine API interface. You must call this function before attempting to use any of the other API procedures. Generally this API procedure is called when your application first initializes.

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

Syntax

C#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE InitializeMediaEngine(
	string RedistributionString,
	uint ThreadStackSizeInBytes
)
Visual Basic (Declaration)
Public Function InitializeMediaEngine ( _
	RedistributionString As String, _
	ThreadStackSizeInBytes As UInteger _
) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE
Visual C++
public:
VoipMediaEngine..::.TELEPHONY_RETURN_VALUE InitializeMediaEngine(
	String^ RedistributionString, 
	unsigned int ThreadStackSizeInBytes
)
J#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE InitializeMediaEngine(
	String RedistributionString,
	UInt32 ThreadStackSizeInBytes
)

Parameters

RedistributionString
Type: System..::.String
While you are developing your VOIP application, this parameter can be zero length string (an empty string like ""). When you are ready to deploy your VOIP application to end user machines, this parameter must be a string that contains your media engine redistribution code. For complete details regarding redistribution of the media engine, see the document entitled "Redistributing LanScape VOIP Media Engine.pdf" located in the "Redist" folder of your product install directory. By specifying your redistribution code string in this parameter, your VOIP application will be able to execute anywhere wihout having to install the the VOIP Media Engine development product image.
ThreadStackSizeInBytes
Type: System..::.UInt32
This value controls the stack size of each internal thread the media engine creates. It can only be used to increase media engine thread stack sizes from the default thread stack size the application uses. To allow default stack size capability per media engine thread, you should set this value to zero. Default thread stack size is usually 1 megabyte (1,048,576 bytes) for 32 bit Windows applications. If you are using a multi-instance media engine, all engine instances will use the thread stack size as set by this parameter. Under most deployment scenarios, this parameter should always be set to zero.
Note:
If you want to dramatically reduce the virtual memory requirements of your application and the memory requirements of the media engine, you should specify a default thread stack size smaller than 1 megabyte in your applications EXE header. Values as low as 4096 bytes can logically be specified. The low range value of 4096 bytes is enforced by the operating system.
Caution:

At LanScape, we routinely lower the default threads stack size in media engine based applications in an effort to greatly lower the memory requirements of large line density VOIP applications. These large line applications are generally 128 lines or greater. If you change the default thread stack size when your application is being linked, you must make sure that your VOIP application will not run out of stack space or generate stack related protected mode violations or stack related faults.

The VOIP Media Engine does not rely heavily on thread stack size in order to operate. In other words, the VOIP Media Engine does not require large thread stack space. However there is a limit to how low you can push thread stacks without generating stack related program crashes.

For additional details regarding how your application can reduce the virtual memory requirements of the media engine, please see the section entitled "Minimizing virtual memory requirements" in this developer's reference.

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 ValueDescription
SipInitializeError
Your application software called the InitializeMediaEngine(String, UInt32) API procedure and the telephony engine initialization operation failed. This error is critical an must be resolved before any telephony operations are possible. Typical causes for this error are low memory situations and thread startup errors.

(API return value)

SipMediaEngineAlreadyInitialized Your application software called the InitializeMediaEngine(String, UInt32) API procedure more than once. You should only call this API procedure once during application startup. This error is for informational purposes.

(API return value)

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.

See Also