1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
Hints for libGammu Novices
==========================
This is very short overview of libGammu usage. You will probably need to study
:doc:`api` to find out what functions you want to use.
Basic library usage
-------------------
You need to include main header file:
.. code-block:: c
#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 struct. This structure is not
public, so all you can define is a pointer to it:
.. code-block:: c
GSM_StateMachine *state_machine;
You'll want to check for errors from time to time. Do it using a
function something like this:
.. code-block:: c
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):
.. code-block:: c
GSM_InitLocales(NULL);
You first need to allocate a state machine structure:
.. code-block:: c
state_machine = GSM_AllocStateMachine();
Now think about the configuration file. To use the default
:file:`~/.gammurc`, do this:
.. code-block:: c
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 (3 means number of replies you want to wait
for in case of failure):
.. code-block:: c
error = GSM_InitConnection(s, 3);
check_error(error);
Now you are ready to communicate with the phone, for example you can read
manufacturer name:
.. code-block:: c
error = GSM_GetManufacturer(s, buffer);
check_error(error);
When you're finished, you need to disconnect and free allocated memory:
.. code-block:: c
error = GSM_TerminateConnection(s);
check_error(error);
/* Free up used memory */
GSM_FreeStateMachine(s);
check_error(error);
There are also other :doc:`examples`.
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:
.. code-block:: c
printf("%s\n", DecodeUnicodeConsole(unicode_string));
For giving string to some GUI toolkit:
.. code-block:: c
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:
.. code-block:: c
debug_info = GSM_GetGlobalDebug();
GSM_SetDebugFileDescriptor(stderr, FALSE, debug_info);
GSM_SetDebugLevel("textall", debug_info);
For per state machine configuration:
.. code-block:: c
debug_info = GSM_GetDebug(s);
GSM_SetDebugGlobal(FALSE, debug_info);
GSM_SetDebugFileDescriptor(stderr, FALSE, debug_info);
GSM_SetDebugLevel("textall", debug_info);
|
