Prosody high level FILE play/record: API: sm_replay_file_start

Prototype Definition

int sm_replay_file_start(struct sm_file_replay_parms *file_parms)

Parameters

*file_parms
a structure of the following type: 
typedef struct sm_file_replay_parms {
	tSM_OPEN_FILE fd;					/* in */
	tSM_UT32 offset;					/* in */
	SM_REPLAY_PARMS replay_parms;				/* in */
	int status;						/* out */
	tSM_UT32 private_length;				/* out */
	int completing;						/* out */
	int data_length_in_buffer;				/* out */
	char buffer[kSMMaxHiReplayDataBufferSize];		/* out */
} SM_FILE_REPLAY_PARMS;

Description

Prepares a channel for replay of data from a file to an output channel previously allocated by a call to sm_channel_alloc_placed().

When using the TiNG dll under Windows use of this function requires a FILE* to be passed across the dll boundry. This may cause problems when the application uses a different C runtime library from the TiNG dll. Since the C runtime library used by the TiNG dll may change in future versions, this function is deprecated when using the TiNG dll.

The fields of the structure replay_parms should be set up as described in sm_replay_start() low level API call. Note the field data_length should either be set to zero or to the actual number of octets to be replayed from the file. If it is set to zero then all of the data starting from offset to the end of the file will be replayed.

The status field is used to indicate the current status of the replay. On return from a successful invocation of sm_replay_file_start() it will be set to a value of ERR_SM_PENDING and will continue to have this value until replay has been completed, aborted or terminated on occurrence of an error.

The fields private_length, data_length_in_buffer and buffer are used internally by the high level library and should not be accessed by the application.

The replay is finished when a call to sm_replay_file_complete() returns.

Fields

fd
The file containing the data to be played. This must have been opened with C standard I/O library function fopen() unless the library was built for Microsoft Windows with the C preprecessor symbol __SMWIN32HLIB__ defined, in which case it must be a Windows HANDLE. It is recommended that the Prosody high level BFILE play/record is used where possible instead of rebuilding this library, since it avoids the risk of accidentally using the library built for the wrong type of file access.
offset
The offset measured in octets (starting from zero) of the first octet of replay data in the file referenced by fd.
replay_parms
A structure as defined for sm_replay_start.
status
The status of the replay.
private_length
A field reserved for the library.
completing
A field reserved for the library.
data_length_in_buffer
A field reserved for the library.
buffer
A field reserved for the library.

Returns

0 if call completed successfully, otherwise a standard error such as:

This function is part of the Prosody high level FILE play/record API.