Speak Freely API

Speak Freely
Application Programming Interface
Draft 0.1 - 06/03/1999

by Brian C. Wiles

Contents
1. Introduction
2. Function Summary
3. Engine Initialization
4. Call Initiation
5. Call Options
6. Call Termination
7. Directory Functions
8. Misc. Functions
9. Structures
10. Failure Codes
11. Implementation Recommendations
12. Notes

Introduction
This specification defines the developer API for the Speak Freely Engine. To make things easier,
the Engine version numbers will remain consistant with the version numbers of the Speak Freely
interface release that uses that Engine. Since the Engine was separated in version 8.0, the first
Engine version is 8.0.

The purpose of this specification is to allow developers of other applications to add Internet
telephony to their existing products, or to develop their own Internet telephone, without having to
know the details of how Voice Over IP (VoIP) works. For example, a game developer can add
realtime virtual radio communications to their latest air combat simulator. The possibilities are
endless, which is why it makes more sense to developers to concentrate their efforts on
developing their unique product rather than having to reinvent the wheel (or, in this case, the
engine).

file:///E|/Eboox/Internet/VoIP/Implementations/SpeakFreely/api.html (1 of 7)2005/09/04 10:46:18 •.•

Speak Freely API

This specification also defines the required behavior of any Speak Freely-compliant engine. All
of the described functions MUST be implemented EXACTLY as described. Generally, however,
it is recommended that developers NOT create their own engine since the full source code of the
official Speak Freely engine is freely available with source code.

Developers are encouraged to contribute their fixes, enhancements, and new platform ports to the
Speak Freely Developers. This will ensure new engines remain stable and makes the software
available to more people on different platforms.

Throughout this specification, the structures and function behavior has been designed to preserve
Speak Freely's compatibility with older versions. Not all structure members should be modified
by the calling application since the engine uses them internally to keep call states consistent and
separate between different sessions. This also allows the engine to remain thread-safe for
multithreaded applications.

Wherever possible, developers should use the Speak Freely engine to communicate using the
chosen protocol, such as H.323 or RTP, and to record and playback audio using the audio
hardware. The encoding and decoding functions are provided only as a method for the
application to further manipulate the data for purposes such as recording to a file or speech
processing (i.e. speech recognition or text-to-speech).

Function Summary
There are several functions for carrying out different tasks via the Engine. Each function will
return FALSE (0) if successful, or a specific failure code if there was a failure. Failure codes are
listed in a later section.

The following is a brief summary and description of all of the API functions covered under this
specification. Notice that all of the functions contain the prefix "SF" to reduce the chances of a
conflict in a parent application:

Function Name (and parameters) Description

SFInitEngine (int MinVersion, int MaxVersion, Initialize the engine, specifying the
SFENGINE* sfEngine) supported engine version(s).
SFCallConnect (IN_ADDR inAddress, SFCALL*
Call someone at a specific IP Address.
sfCall)
Get current compression/encryption
SFCallGetOptions (SFCALL* sfCall)
options for specified call.

file:///E|/Eboox/Internet/VoIP/Implementations/SpeakFreely/api.html (2 of 7)2005/09/04 10:46:18 •.•

Speak Freely API

Set compression/encryption options for

SFCallSetOptions (SFCALL* sfCall)
specified call.
SFCallTerminate (SFCALL* sfCall) Terminate (hang up) the specified call.
Look someone up in the Look Who's
SFDirectoryLookup (SFUSER* sfUser)
Listening directory.
SFDirectoryPublish (SFUSER* sfUser, int Publish/hide local user information in
bPublish) LWL directory.
Close the engine and free allocated
SFCloseEngine (SFENGINE* sfEngine)
resources.
SFEncodePacket (SFCALL* sfCall, SFPACKET* Encrypt and/or compress audio data for
sfPacket, char* pSamples) transport via Speak Freely.
SFDecodePacket (SFCALL* sfCall, SFPACKET* Decrypt and/or decompress audio data
sfPacket, char* pSamples) from Speak Freely packet.
SFShipPacket (SFCALL* sfCall, SFPACKET*
Send the sound to the other party.
sfPacket)

Engine Initialization

Call Initiation

Call Options

Call Termination

Directory Functions

file:///E|/Eboox/Internet/VoIP/Implementations/SpeakFreely/api.html (3 of 7)2005/09/04 10:46:18 •.•

Speak Freely API

Callback Functions
int AcceptConnection (SFCALL* sfCall)

This function should evaluate the incoming call data via the sfCall structure
and return FALSE (0) if the connection should be rejected, or TRUE (-1) if
the connection should be accepted.

Misc. Functions

Structures
The structures the engine uses are as follows:

SFENGINE
{

int iVersionMajor; // The major API version (e.g. the '8' in version 8.0)
int iVersionMinor; // The minor API version (e.g. the '0' in version 8.0)
char szVendor[100]; // The name of the author/vendor of this engine (e.g. "Speak Freely
Developers")
char szName[100]; // The name of the engine (e.g. "Speak Freely")
char szEngineVersion[100]; // This engine implementation's version number (vendor-
specific string, may be different than API version)
int* pfnAcceptConnection; // This function is called when a connection arrives. This
can be NULL if every connection should be accepted.
}

SFCALL
{

DWORD dwType; // Type of window (WINDOW_TYPE_CLIENT)

CLIENT_STATE state; // Current state.
SOCKET sReply; // Socket waiting for reply from srv
SOCKET sControl; // Socket for RTP/VAT control messages
int timeout; // Timeout counter
SOCKADDR_IN inetSock; // Client's socket address
unsigned short port; // Destination data port number
struct auxSocket *auxSock; // Auxiliary socket, if any

file:///E|/Eboox/Internet/VoIP/Implementations/SpeakFreely/api.html (4 of 7)2005/09/04 10:46:18 •.•

Speak Freely API

CHAR szHost[MAX_HOST]; // Target server's host name

HFILE hFile; // Handle to open file
DWORD cbSent; // Count of bytes sent so far.
DWORD cbReceived; // Count of bytes received so far
CHAR szFile[MAX_PATH]; // Name of file being sent
HANDLE getNameTask; // Get full site name task handle
BYTE hostBuffer[MAXGETHOSTSTRUCT];// Host name reply buffer
int modemConnection; // Connection is via the modem
HMMIO mmioHandle; // WAVE file MMIO handle
LPWAVEFORMAT mmioFormat; // WAVE file format descriptor
DWORD mmioDataLeft; // WAVE file data left to send
int quitSoundFile; // Abort current sound file ?
int wantsInput; // Is wave input wanted ?
int outputSocketBusy; // Output socket is busy with a sendto()
DWORD broadcastBeginTime; // Time (ticks) when subscribed to broadcast
int broadcastEnd; // Terminate broadcast connection ?
struct sockaddr_in name; // Target system address
struct sockaddr_in ctrl; // Target system control port address
char desKeyString[256]; // DES key string
char deskey[9]; // Destination DES key, if any
char rtpdeskey[9]; // Destination RTP DES key, if any
char vatdeskey[9]; // Destination VAT DES key, if any
char ideaKeyString[256]; // IDEA key string
char ideakey[17]; // Destination IDEA key, if any
char blowfishKeyString[256]; // Blowfish key string
char blowfish_spec; // Is Blowfish key specified?
BF_KEY blowfishkey; // Generated Blowfish key
char pgpkeymd5[16]; // Inbound MD5 signature of PGP session key
char pgpkey[17]; // Inbound PGP-transmitted session key
char pgpFileName[MAX_PATH]; // Inbound PGP decoded file name, if strlen >0
char opgpUserList[256]; // Outbound PGP user ID list
char opgpkey[17]; // Outbound PGP-transmitted session key
char opgpFileName[MAX_PATH]; // Outbound PGP decoded file name, if strlen >0
char otpFileName[MAX_PATH]; // One-time pad file name
char otp[BUFL]; // One-time pad
int multicast_scope; // Multicast scope (time-to-live)
int squelch; // Squelch
int ring; // Ring
int debugging; // Debug mode
int debugReq; // Debug output requested by remote ?
int loopback; // Loopback mode
int saveKeys; // Save keys in connection file
char connectionFileName[MAX_PATH];// Connection file name for save

file:///E|/Eboox/Internet/VoIP/Implementations/SpeakFreely/api.html (5 of 7)2005/09/04 10:46:18 •.•

Speak Freely API

gsm gsmh; // GSM handle

lpcstate_t lpc_state; // LPC decoder state
rate_t rateconv; // Rate conversion state
int rseq; // Robust mode packet sequence number
short protocol; // Transmission protocol
short localLoopback; // Local loopback enabled ?
struct localLoop *llhead, // Local loopback packet chain
*lltail;
char session_id[4]; // VAT/RTP session identifier
int sendSDEStimer; // Sent RTP/VAT ID timer
int buttonUpTimer; // Button up timer running
LPSTR uname; // User name, if known
char email[256]; // User E-mail address, if known
int face_stat; // Face retrieval status
long face_address; // Address of current block request
int face_retry; // Timeout retry count
int face_timeout; // Timeout interval
LPSTR face_bmp; // In memory copy of face .bmp file
int face_is_gif; // Face being received as .gif file
long face_file_length; // Length of face file being received
int face_shown; // Face bitmap currently displayed ?
int bSentOutgoingMessage;// Sent outgoing message already.
void FAR* pfnCallback; // The function to call when a packet of data arrives.
}

SFUSER
{

void FAR* next; // Next connection

long ltime; // Time of last update
unsigned long ssrc; // Session source descriptor
long naddr; // Internet address
unsigned short port; // Port address
LPSTR cname; // Canonical name
LPSTR name; // User name
LPSTR email; // Electronic mail address
LPSTR phone; // Telephone number
LPSTR loc; // Geographic location
LPSTR tool; // Application name
}

SFPACKET
{

file:///E|/Eboox/Internet/VoIP/Implementations/SpeakFreely/api.html (6 of 7)2005/09/04 10:46:18 •.•

Speak Freely API

LONG compression; // Compression and encryption flags for this packet.

char sendinghost[16]; // Host data used internally by engine.
struct
{
LONG buffer_len; // The length of the encoded buffer
char buffer_val[BUFL]; // The actual compressed and/or encrypted bytes.
} buffer;
DWORD dwSequence; // Packet sequence number for this call, used to detect lost or
duplicate packets.
}

Failure Codes

Implementation Recommendations

Notes

file:///E|/Eboox/Internet/VoIP/Implementations/SpeakFreely/api.html (7 of 7)2005/09/04 10:46:18 •.•