|
SBClient - C Language APIIntroduction
The SBClient 'C' language API provides a number of functions allowing a application generic access to a speech/braille device. In order to use the functions the application should be linked with the library libsbdev.a .
Applications wishing to use the library should include the following header file :-
#include sbdevc.h
Library Functions
int SBDevOpen(SBDevP* sbDev,char* host,int port,char* name);Opens a connection to an sbserver program on the specified host machine and expected to be listening on the specified port. host is the name or IP address of the host running the SBServer deamon. port is the TCP/IP port number. Both host and port parametersare optional, where host is not specified local host is assumed and connection port determined by lookup for the service type sbserver (Ref: /etc/services). This function must be called prior to the use of any other. name is a name for the connection refference , typically the name of the application and is one of the strings returned by call to SBDevGetConnectionNames(). The SBDevP value in location sbDev on return is the refference that must used by all other functions.
int SBDevClose(SBDevP sbDev)
Closes the connection to the server specified by sbDev.int SBGetVersion(SBDevP sbDev,int* major,int* minor,int* release);
Obtains the version details of the connected server. Version identification is in the form of three digits ordered major,minor and release. eg 3.4.6.
int SBDevLock(SBDevP sbDev,SBDevMode lock);
Locks the speech/braille server to the given connection. The lock parameter allows either input, output or both to be locked.int SBDevGetConnectionNames(SBDevP sbDev, SBDevStringList* names);
Return the list names of connections made to the server. The names returned are as passed by the application with the SBDevOpen() call. This call allocates space which should by freed by calling SBDevFreeStringList(list) where list is the value returned in names following a SBDevGetConnectionNames() call. eg. SBDevFreeStringList(*names).int SBDevGetConnectionHistory(SBDevP sbDev, char* conName, int line, SBDevDevice device, char* string);
Obtain strings passed to a Speech/braille device by the server. conName identifies the connection stream to query, device the actual device. line specifies an index as to which string to return 0 being the latest utterance, 1 the penultimate etc. The string is placed as indicated by the names parameter.
int SBDevBrailleSetMode(SBDevP sbDev,char* mode);
Sends configuration string mode to the braille device. The functionality of the string is Braille device specific.int SBDevBrailleGetModes(SBDevP sbDev,char* modes);
Obtains the current modes in the form of a string which is copied into the buffer pointer to by modes. The modes buffer should be of a size capable of holding the returned data.int SBDevBrailleDisplayBraille(SBDevP sbDev,char* string);
Displays the specified string on the braille display text line cells.int SBDevBrailleDisplayStatus(SBDevP sbDev,int pos, char data, char ul);
Display the character specified by data on the status cell pos (pos = 0 = Leftmost cell). ul indicates if the character should be underlined.int SBDevBrailleDisplayCursor(SBDevP sbDev,int pos, int show);
Display the cursor at cell pos. show indicates if the cursor is to be shown (show = 1) for on (show = 0) for off.int SBDevBrailleShift(SBDevP sbDev,int shift);
A braille display has a limited number of cells with which to display a line of text. The shift parameter sets the absolute shift from the start of the text. eg. The braille display shows "abcdefgh". If a shift of 1 is set the display becomes "bcdefg", a shift of 4 gives "efg". A further shift of 1 reverts to "bcdefg".int SBDevBrailleGetNumberDisplayed(SBDevP sbDev,int* num);
On return num contains the number of text cells used.
int SBDevBrailleGetNumberofCells(SBDevP sbdev,int* num);
num is filled with the number of character cells. An Alva 440 40 cells display returns 40.int SBDevBrailleGetName(SBDevP sbdev,char* name);
The name of the Braille display is copied into name.
int SBDevBrailleGetKey(SBDevP sbdev,int* key, SBDevKeyType* ktype, int* mod);
The BrailleGetKey function obtains the keypresses on the braille display. When called the function will block until a key is pressed, for non-blocking key detection use the SBDevBrailleGetFD() function. The three parameters are used to determine the exact keyint SBDevSpeechSpeak(SBDevP sbdev,char* string, int* index = 0);
pressed.
ktype key SBDEV_MAIN Indicates a key press from the set SBDevKey (Ref: sbdevc.h) SBDEV_STATUS1 Key position in the lower row above status cells SBDEV_STATUS2 Key position in the upper row above status cells SBDEV_BUTS1 Key position in lower row above display cells SBDEV_BUTS2 Key position in upper row above display cells
Output the string string as speech.The optional parameter index provides a value that may be used to triggerint SBDevSpeechStop(SBDevP sbdev,);
the function specified by SpeechCallWhenReached() when the sound has been ouput.
Stop speaking. This function will terminate any speech 'stacked up' and awaiting to beint SBDevSpeechSound(SBDevP sbdev,SoundType sound, int* index = 0);
spoken.
Output the specified sound. The optional parameter index provides a value that may be used to triggerint SBDevSpeechSet(SBDevP sbdev,SpeechSettings settings);
the function specified by SpeechCallWhenReached() when the sound has been ouput.
Configure the speech settings such as voice type, pitch and speed.
typedef struct { SBDevVoice voice; /* SBDEV_MALE, SBDEV_FEMALE etc */ int speed; /* 1 - 100 slow -> fast */ int volume; /* 1 - 100 quiet -> loud */ int pitch; /* 1 - 100 low -> high */ } SBDevSpeechSettings; int SBDevSpeechGet(SBDevP sbdev,SpeechSettings* settings); Obtain the current speech settings, voice type pitch,speed etc. Refer to SBDevSpeechSet() for details on settings structure.int SBDevSpeechGetName(SBDevP sbdev,char* name);
name is filled with the name of the sound device.int SBDevSpeechCallWhenReached(SBDevP sbdev,int item, Function func);
Call the specifed function func when item has been output<back >