The StartPhoneLineRecording procedure allows application software to start full duplex call recording for any specified phone line. All call recording details are handled internally and required no additional application intervention. Any RTP media data that enters or leaves the specified phone line will be processed and digitally mixed. The resulting audio data can then be presented to the application as sample blocks or written directly to a multimedia file.

To stop recording phone line audio application software should call the StopPhoneLineRecording API procedure.

Application software can use the VOIP Media Engine call recording capabilities in two distinct ways:

Recording portions of phone calls:

When a phone call is actively streaming RTP media, application software can start and stop call recording on any phone line at any time. If the application has specified to receive mixed sample blocks from the Media Engine, the application can process the audio sample blocks as required.

If application software has specified that multimedia sample data files be created, then a new sample file containing the recorded audio will be created every time call recording is turned on.

Recording all phone calls:

Application software can alternatively enable phone line recording once. This can be performed at any time after the media engine has been initialized. If a new call is initiated or received, the media engine will automatically start to record the phone line audio data when the call is actively sending and receiving RTP media data.

In this mode, application software can receive all recorded sample blocks directly or the media engine can create multimedia sample files for later playback. Call recording will then stop as soon as the phone call terminates.

If you initiate or receive another phone call, call recording will once again start automatically sending your application sample data blocks or creating another multimedia sample file.

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

Syntax

C#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE StartPhoneLineRecording( VoipMediaEngine MediaEngine, int PhoneLine, bool RecordToFile, bool RecordFileRaw, bool RecordTransmitAudio, bool RecordReceivedAudio, int RecordDelayMs, string PhoneLineRecordDirectory, VoipMediaEngine..::.PHONE_LINE_RECORD_CALLBACK_PROC PhoneLineRecordCallback, Object UserData )

public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE StartPhoneLineRecording(
	VoipMediaEngine MediaEngine,
	int PhoneLine,
	bool RecordToFile,
	bool RecordFileRaw,
	bool RecordTransmitAudio,
	bool RecordReceivedAudio,
	int RecordDelayMs,
	string PhoneLineRecordDirectory,
	VoipMediaEngine..::.PHONE_LINE_RECORD_CALLBACK_PROC PhoneLineRecordCallback,
	Object UserData
)

Visual Basic (Declaration)
Public Function StartPhoneLineRecording ( _ MediaEngine As VoipMediaEngine, _ PhoneLine As Integer, _ RecordToFile As Boolean, _ RecordFileRaw As Boolean, _ RecordTransmitAudio As Boolean, _ RecordReceivedAudio As Boolean, _ RecordDelayMs As Integer, _ PhoneLineRecordDirectory As String, _ PhoneLineRecordCallback As VoipMediaEngine..::.PHONE_LINE_RECORD_CALLBACK_PROC, _ UserData As Object _ ) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE

Visual Basic (Declaration)

Public Function StartPhoneLineRecording ( _
	MediaEngine As VoipMediaEngine, _
	PhoneLine As Integer, _
	RecordToFile As Boolean, _
	RecordFileRaw As Boolean, _
	RecordTransmitAudio As Boolean, _
	RecordReceivedAudio As Boolean, _
	RecordDelayMs As Integer, _
	PhoneLineRecordDirectory As String, _
	PhoneLineRecordCallback As VoipMediaEngine..::.PHONE_LINE_RECORD_CALLBACK_PROC, _
	UserData As Object _
) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE

Visual C++
public: VoipMediaEngine..::.TELEPHONY_RETURN_VALUE StartPhoneLineRecording( VoipMediaEngine^ MediaEngine, int PhoneLine, bool RecordToFile, bool RecordFileRaw, bool RecordTransmitAudio, bool RecordReceivedAudio, int RecordDelayMs, String^ PhoneLineRecordDirectory, VoipMediaEngine..::.PHONE_LINE_RECORD_CALLBACK_PROC^ PhoneLineRecordCallback, Object^ UserData )

Visual C++

public:
VoipMediaEngine..::.TELEPHONY_RETURN_VALUE StartPhoneLineRecording(
	VoipMediaEngine^ MediaEngine, 
	int PhoneLine, 
	bool RecordToFile, 
	bool RecordFileRaw, 
	bool RecordTransmitAudio, 
	bool RecordReceivedAudio, 
	int RecordDelayMs, 
	String^ PhoneLineRecordDirectory, 
	VoipMediaEngine..::.PHONE_LINE_RECORD_CALLBACK_PROC^ PhoneLineRecordCallback, 
	Object^ UserData
)

J#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE StartPhoneLineRecording( VoipMediaEngine MediaEngine, int PhoneLine, boolean RecordToFile, boolean RecordFileRaw, boolean RecordTransmitAudio, boolean RecordReceivedAudio, int RecordDelayMs, String PhoneLineRecordDirectory, VoipMediaEngine..::.PHONE_LINE_RECORD_CALLBACK_PROC PhoneLineRecordCallback, Object UserData )

public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE StartPhoneLineRecording(
	VoipMediaEngine MediaEngine,
	int PhoneLine,
	boolean RecordToFile,
	boolean RecordFileRaw,
	boolean RecordTransmitAudio,
	boolean RecordReceivedAudio,
	int RecordDelayMs,
	String PhoneLineRecordDirectory,
	VoipMediaEngine..::.PHONE_LINE_RECORD_CALLBACK_PROC PhoneLineRecordCallback,
	Object UserData
)

Parameters

MediaEngine: Type: LanScape..::.VoipMediaEngine
An instance of the media engine.

PhoneLine: Type: System..::.Int32
The zero based phone line that will have call recording enabled.

RecordToFile

Type: System..::.Boolean
If set to a non zero value, the media engine will write recorded digitally mixed sample blocks to a multimedia data file. If set to zero, no recorded sample data files will be created. In this case, the RecordFileRaw and PhoneLineRecordDirectory parameters are ignored.

When recording phone line audio to multimedia files, the media engine will send the SipCallRecordActive event to the application any time call recording starts. If your application processes the SipCallRecordActive event, you will be given access to the full path file name that will contain the recorded audio.

If at any time the media engine detects an error with writing the record sample file, it will send the SipCallRecordFileWriteError event to the application.

RecordFileRaw: Type: System..::.Boolean
If set to a non zero value, the media engine will create a multimedia sample file containing raw 8k PCM samples. If set to zero, the media engine will create a wave file containing 8k PCM sampled data.

RecordTransmitAudio: Type: System..::.Boolean
If set to a non zero value, the media engine will record phone line transmit audio. If this parameter and the RecordReceivedAudio parameter are both set to non zero, then transmitted and received phone line audio will be digitally mixed and recorded.

RecordReceivedAudio: Type: System..::.Boolean
If set to a non zero value, the media engine will record phone line received audio. If this parameter and the RecordTransmitAudio parameter are both set to non zero, then received and transmitted phone line audio will be digitally mixed and recorded.

RecordDelayMs: Type: System..::.Int32
Allows the application to specify a record delay. Normally this value is set to 0 milliseconds. If a record delay is specified that is greater than zero, recorded call audio will only be written to disk or sent to the application when the record delay has elapsed. Note that specifying large values of record delay will cause the media engine to use additional memory for the record delay buffers. Record delay is most often used by applications to truncate the end of recorded call audio files by the specified delay amount when turning off call recording for a call.

PhoneLineRecordDirectory: Type: System..::.String
When enabling the creation of multimedia sample data files, this parameter specifies the directory where the recorded audio files will be written.
When the media engine creates a new record data file in this directory, it will create a randomly named file with a ".dat" or ".wav" file extension. The actual file extension used for the recorded audio data file depends on the value specified for the RecordFileRaw parameter above.

PhoneLineRecordCallback: Type: LanScape..::.VoipMediaEngine..::.PHONE_LINE_RECORD_CALLBACK_PROC
If application software wants to receive recorded sample blocks directly, this callback address can be specified. the callback procedure will be called whenever the media engine has a new recorded phone line sample block buffer. Note that this callback will be given access to the recorded phone line audio data (20 Ms of 8k PCM audio data). The callback may change the PCM samples if desired. Any changes to the recorded phone line sample buffer will be written to the record file image if recording to a file has been enabled.

UserData: Type: System..::.Object
A user supplied data value. This data value is passed to the PhoneLineRecordCallback procedure via the VoipMediaEngine..::.PHONE_LINE_RECORD_DATA class.

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)
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)
SipBadPhoneLine	Application software called a telephony API procedure and specified an invalid phone line. Phone lines are numbered starting from zero. This error is most commonly returned when attempting to access phone lines in excess of the max number of lines supported by the telephony engine. (API return value)
SipCallRecordNotEnabled	The media engine must be instantiated with call recording enabled before application software can call any of the phone line record API procedures. See the EnablePhoneLineRecording value of the VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS structure. (API return value)
SipDirectoryDoesNotExist	The telephony engine attempted to access an application supplied directory that 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)
SipCallRecordFilenameNotCreated	The SipCallRecordFilenameNotCreated event is sent to an application when the media engine tries to start phone line recording and it cannot create a unique record file name. In this case, no phone line recording will take place. This event will only be sent if recording to a file is enabled. (API return value, IMMEDIATE_NOTIFICATION)
SipCallRecordSampleFileNotCreated	The SipCallRecordSampleFileNotCreated event is sent to an application when the media engine tries to start call recording and the record sample file image cannot be created. If the application receives this event, no call recording will take place. To resolve this error, make sure there is enough free disk space on the host machine and that the target directory is not write protected. When an application receives this event, the media engine event callback procedure VoipMediaEngine..::.SIPCALLBACKPROC will have a reference value assigned to the EventData parameter. This value is a reference to the filename that was used when the attempt was made to create the sample record file. (API return value, IMMEDIATE_NOTIFICATION)
SipCallRecordAlreadyStarted	Application software called the StartPhoneLineRecording(VoipMediaEngine, Int32, Boolean, Boolean, Boolean, Boolean, Int32, String, VoipMediaEngine..::.PHONE_LINE_RECORD_CALLBACK_PROC, Object) API procedure and call recording was already started. (API return value)

Remarks

If your application allows the media engine to automatically create sample data files containing recorded phone line audio, all recorded sample data is written to a randomly named file using raw PCM samples. If your application has specified that it wants wave file format, the final wave file image will only be created when phone line recording has been turned off or when the phone call terminates.

Caution:
Do not try to perform file operations on the record sample file when phone line call recording is performing its tasks.

Accessing the name of the file used to record audio: See the SipCallRecordActive event for further details. One of the callback parameters of the event contains a reference to a character string that contains the full path file name used for recorded audio.

Syntax

Parameters

Return Value

Remarks

See Also