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).

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, SFENGINE* sfEngine)	Initialize the engine, specifying the supported engine version(s).
SFCallConnect (IN_ADDR inAddress, SFCALL* sfCall)	Call someone at a specific IP Address.
SFCallGetOptions (SFCALL* sfCall)	Get current compression/encryption options for specified call.
SFCallSetOptions (SFCALL* sfCall)	Set compression/encryption options for specified call.
SFCallTerminate (SFCALL* sfCall)	Terminate (hang up) the specified call.
SFDirectoryLookup (SFUSER* sfUser)	Look someone up in the Look Who's Listening directory.
SFDirectoryPublish (SFUSER* sfUser, int bPublish)	Publish/hide local user information in LWL directory.
SFCloseEngine (SFENGINE* sfEngine)	Close the engine and free allocated resources.
SFEncodePacket (SFCALL* sfCall, SFPACKET* sfPacket, char* pSamples)	Encrypt and/or compress audio data for transport via Speak Freely.
SFDecodePacket (SFCALL* sfCall, SFPACKET* sfPacket, char* pSamples)	Decrypt and/or decompress audio data from Speak Freely packet.
SFShipPacket (SFCALL* sfCall, SFPACKET* sfPacket)	Send the sound to the other party.

Engine Initialization

Call Initiation

Call Options

Call Termination

Directory Functions

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
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
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
{

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