Hints for libGammu Novices¶
This is very short overview of libGammu usage. You will probably need to study libGammu C API to find out what functions you want to use.
Basic library usage¶
You need to include main header file:
#include <gammu.h>
To compile you need to pass flags from pkg-config:
pkg-config --cflags gammu
To link you need to pass from pkg-config:
pkg-config --libs gammu
Gammu stores all its data in a GSM_StateMachine
. This structure is not
public, so all you can define is a pointer to it:
GSM_StateMachine *state_machine;
You’ll want to check for errors from time to time. Do it using a
function something like this with help of GSM_ErrorString()
:
void check_error(GSM_Error err)
{
if (err == ERR_NONE) {
return;
}
fprintf(stderr, "Gammu failure: %s\n", GSM_ErrorString(error));
exit(1);
}
As libGammu does interact with strings in your local encoding, it is good idea
to initialize locales subsystem first (otherwise you would get broken non
ASCII characters) by calling GSM_InitLocales()
:
GSM_InitLocales(NULL);
You first need to allocate a state machine structure
using GSM_AllocStateMachine()
:
state_machine = GSM_AllocStateMachine();
Now think about the configuration file. To use the default
~/.gammurc
, do this:
INI_Section *cfg;
/* Find it */
error = GSM_FindGammuRC(&cfg, NULL);
check_error(error);
/* Read it */
error = GSM_ReadConfig(cfg, GSM_GetConfig(state_machine, 0), 0);
check_error(error);
/* Free allocated memory */
INI_Free(cfg);
/* We care onlu about first configuration */
GSM_SetConfigNum(s, 1);
OK, now initialise the connection (1 means number of replies you want to wait
for in case of failure) by GSM_InitConnection()
:
error = GSM_InitConnection(s, 1);
check_error(error);
Now you are ready to communicate with the phone, for example you can read
manufacturer name by GSM_GetManufacturer()
:
error = GSM_GetManufacturer(s, buffer);
check_error(error);
When you’re finished, you need to disconnect and free allocated memory
using GSM_FreeStateMachine()
:
error = GSM_TerminateConnection(s);
check_error(error);
/* Free up used memory */
GSM_FreeStateMachine(s);
check_error(error);
There are also other Examples.
Compiling the code¶
To compile program using Gammu library, you need to pass include path to the
compiler and library name and search path to the linker. This can be easiest
achieved by using pkg-config. See following Makefile
for
example:
# Sample Makefile which can be used to build examples shipped with Gammu
CFLAGS=$(shell pkg-config --cflags --libs gammu-smsd) -Wall
LDFLAGS=$(shell pkg-config --cflags --libs gammu)
ALL=phone-info sms-send smsd
.PHONY: all clean
all: $(ALL)
clean:
rm -f $(ALL)
%:%.c
$(CC) $< $(CFLAGS) $(LDFLAGS) -o $@
Unicode¶
Gammu stores all strings internally in UCS-2-BE encoding (terminated by two
zero bytes). This is used mostly for historical reasons and today the obvious
choice would be wchar_t
. To work with these strings, various functions
are provided (UnicodeLength()
, DecodeUnicode()
,
EncodeUnicode()
, CopyUnicodeString()
, etc.).
For printing on console you should use:
printf("%s\n", DecodeUnicodeConsole(unicode_string));
For giving string to some GUI toolkit:
printf("%s\n", DecodeUnicodeString(unicode_string));
Note
These functions differ only on platforms where console uses historically different character set than GUI, what effectively means only Microsoft Windows.
Debugging¶
You can either enabled debug logging globally or per state machine.
To enable global debugging use:
debug_info = GSM_GetGlobalDebug();
GSM_SetDebugFileDescriptor(stderr, FALSE, debug_info);
GSM_SetDebugLevel("textall", debug_info);
For per state machine configuration:
debug_info = GSM_GetDebug(s);
GSM_SetDebugGlobal(FALSE, debug_info);
GSM_SetDebugFileDescriptor(stderr, FALSE, debug_info);
GSM_SetDebugLevel("textall", debug_info);
Waiting for incoming events¶
If you expect some incoming events, you need to maintain communication with the
phone. The best way it can be GSM_ReadDevice()
. For example you can use
following busy loop:
while (!gshutdown) {
GSM_ReadDevice(s, TRUE);
}