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 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 :c:type:`GSM_StateMachine`. 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 with help of :c:func:`GSM_ErrorString`: .. 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) by calling :c:func:`GSM_InitLocales`: .. code-block:: c GSM_InitLocales(NULL); You first need to allocate a state machine structure using :c:func:`GSM_AllocStateMachine`: .. 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 (1 means number of replies you want to wait for in case of failure) by :c:func:`GSM_InitConnection`: .. code-block:: c 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 :c:func:`GSM_GetManufacturer`: .. code-block:: c error = GSM_GetManufacturer(s, buffer); check_error(error); When you're finished, you need to disconnect and free allocated memory using :c:func:`GSM_FreeStateMachine`: .. 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`. 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 :program:`pkg-config`. See following ``Makefile`` for example: .. code-block:: make # 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 (:c:func:`UnicodeLength`, :c:func:`DecodeUnicode`, :c:func:`EncodeUnicode`, :c:func:`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); Waiting for incoming events --------------------------- If you expect some incoming events, you need to maintain communication with the phone. The best way it can be :c:func:`GSM_ReadDevice`. For example you can use following busy loop: .. code-block:: c while (!gshutdown) { GSM_ReadDevice(s, TRUE); }