High level play and record functions provide a way to play and record directly using files rather than having to copy the data between the file and the Prosody channel.
Note: the library which provides this API is equivalent to the
Prosody high level BFILE play/record API
library except that instead of using the bfile
library, it uses the C standard library, stdio.
Under Solaris, stdio is crippled by the limitation that it
only works when fewer than 256 file descriptors are opened (it stores
the file descriptor in a char field). Under Windows, there can
be problems using stdio when the application uses a different
C runtime library from the TiNG dll. On other systems,
there is no particular need to use either in preference to the other.
The high level play/record library provides a simple way to play from and record into files. For example, an application could play a file by merely invoking sm_replay_file_start() and sm_replay_file_complete().
Alternatively if the application requires replay of a file as a background task, it might invoke sm_replay_file_start() and then spawn a thread that invokes sm_replay_file_complete(). If the replay had to be prematurely aborted, the main thread of the application could call sm_replay_file_stop(). to abort the replay thread.
If an application had its own replay scheduling method, (perhaps in a multi-threaded application), it could initiate a file replay using sm_replay_file_start() and then periodically call sm_replay_file_progress() and when finishing the replay call sm_replay_file_complete().
Recording of data into a file is done in a similar manner using the calls: sm_record_file_start(), sm_record_file_progress(), sm_record_file_complete() and sm_record_file_stop().
The declarations for this library are in highapi/smhlib.h
and applications using this library must be linked with the
appropriate object file, which is
highapi/gen-LINUX_V6/smhlib.o
(Linux),
highapi/gen-QNX/smhlib.o
(QNX),
highapi/gen-SOL_32_V6/smhlib.o (Solaris)
highapi/gen-WINNT_V6/smhlib.obj
(Windows).
See also the Prosody WAV file API.
From time to time new features are added to this API. This may require new fields to be added to structures. A mechanism is available to ensure that this does not cause any problems for code developed prior to the addition. This is achieved by defining all new fields such that the value zero selects backward compatible behaviour. To take advantage of this, structures should be cleared before use. For example,
SM_FILE_REPLAY_PARMS ap; memset(&ap, 0, sizeof(ap)); ap.fd = file; ... etc
This ensures that if a new field is ever added to this structure the new field is not left uninitialised.
The list of error codes that a function can return is only a list of typical errors. If a function is described as returning a standard error then it can return any such error. Also, when the description of a function says that it can return a particular error code (for example, ERR_SM_FIRMWARE_NOT_RUNNING), this does not mean that the function guarantees to detect this error condition in all circumstances. It merely means that if it does detect this error condition, then this is the code it will return.
This API is part of Prosody.