## Gammu internals

### gammurc Configuration file

When started, Gammu looks for the file “gammurc”, which contains startup definitions in a Windows INI manner. For a 6210 on COM1, the file may looks like this:

`[gammu]`
`model = 6210`
`port=com1:`
`connection=dlr3`

Though Gammu has support for automatically identifying the connected device, still port number and connection type need to be specified. Including the model definition speeds up things since the identifying process is skipped.

These are the currently possible values for connection:

Connection | Details
`at19200` `at115200` | AT commands over serial ports
`fbus` `mbus` | Nokia’s proprietary wiring and protocols
`dlr3` | Nokia fbus protocol over DLR3 cable
`Irda` `infrared` | Infrared with irDA standard or Nokia fbus
`atblue` | AT over Bluetooth
`dlr3blue` | Nokia fbus over Bluetooth (init using method from DLR3 cable)

### Architecture

Marcin Wiacek, author of Gammu, did a very good job at abstracting the various levels he uses, enabling developers to add new features very quickly. We could, for example, add definitions for a new phone and for the most part it wouldn’t matter whether it’s connected locally, via infrared, or (evolving) via Bluetooth.

These are the different abstraction levels:

Title | Description | Defined in…
Configuration parser | Parses gammurc file | cfg
Connections | Provides interfaces for serial, infrared and Bluetooth communications | common\device
Protocols | Defines protocols for Nokia, AT and Alcatel phones | common\protocol
Phones | Specific and general implementations for the supported phone series | common\phone
Service | Provides access to the phone functions – main point of interest for application development | common\service

### Phone function reference

The following phone functions are possible, support varies by phone:

Name | Description
AnswerCall | Accept currently incoming call
CancelCall | Deny currently incoming call
DialVoice | Call number and establish voice call
EnterSecurityCode | Allow to "enter" pin/puk/pin2/puk2, when phone prompts for it on screen
Get/Set/DeleteWAPBookmark | Obvious
Get/Set/SendSMSMessage GetNextSMSMessage DeleteSMS | Obvious
Get/SetAlarm | Obvious
Get/SetBitmap | Obvious
Get/SetCalendarNote DeleteCalendarNote | Obvious
Get/SetDateTime | Obvious
Get/SetMemory | Retrieve and set various telephone numbers, like phonebook entries in the internal memory and on the SIM card, dialed/missed/received logs as well as the phone’s own number
Get/SetProfile | Profile data such as ringtone volume, key sound etc.
Get/SetRingtone | Obvious
Get/SetSMSC | Get/Set the number of the SMS Service Center
Get/SetSpeedDial | a.k.a. dialing shortcuts
Get/SetTodo DeleteAllTodo | Obvious
Get/SetWAPSettings | Dial-up settings
GetBatteryLevel | Obvious
GetDisplayStatus | See on-screen notification icons (new SMS etc.)
GetHardware | Get hardware info
GetIMEI | Retrieve the International Mobile Equipment Identity number
GetManufactureMonth | Obvious
GetManufacturer | Obvious
GetMemoryStatus | Retrieve information about capacity and usage of specific memory
GetNetworkInfo | Retrieve network name, code, current cell, location area code, net status (home/roaming/searching network/no network)
GetNetworkLevel | Network signal strength
GetOriginalIMEI | Obvious
GetPPM | Get name of phone’s language package (Nokia)
GetProductCode | Manufacturer-specific
GetRingtonesInfo | Get ringtone names
GetSecurityStatus | Figure out what code (PIN, Security Code, PIN2, PUK, PUK2), is being prompted by the phone, if any
GetSIMIMSI | International Mobile Subscriber Identity number assigned to SIM card
GetSMSFolders | Retrieve names of SMS folders
GetSMSStatus | Statistics about SMS memory usage
PlayTone | Play tone on phone…
PressKey | Simulate any key push to phone!
Reset | Soft/hard phone reset
ResetPhoneSettings | Obvious
SendDTMF | Numeric key tones
SetAutoNetworkLogin | Obvious
SetIncomingCall | Trigger notification for incoming calls
SetIncomingCB | Trigger notification for incoming CB messages
SetIncomingSMS | Trigger notification for incoming SMS messages

### Services

Furthermore, Gammu offers the following “services” (see first table):

Title | Description | Defined in…
Backup | Complete backup/restore of phone data | gsmbackup.c
Logo | Functions to read, write, resize and convert bitmaps and operator logos and animations | gsmlogo.c
Networks | Pretty extensive table to link GSM operator network codes to the actual operator names | gsmnet.c
Phonebook | VCard support (currently minimal) | gsmpbk.c
Calendar | VCalendar support | gsmcal.c
Ringtones | Functions to read, write and convert ringtone data in various formats | gsmring.c
SMS | Encode and decode various SMS formats, including multi-part messages | gsmsms.c
WAP bookmarks | Encoding support for Nokia WAP bookmarks | gsmwap.c

Be sure to also take a look at gammu.c, which offers additional functionality such as data message composition/sending (wap settings – no gprs/syncml; vcards, calendar items, ringtones, logos, sms center settings, bookmarks). Check out the Readme in the docs/ directory.

## Writing code based on Gammu

Though Gammu is meant to be a single application, one can simply import all its classes and headers and make use of them. The easiest way to do this is to copy all the includes and global variables (s, *Phone, etc., see below for details) from the main class gammu.c. into one’s own main class. When using Gammu in a C++ project, it is mandatory to use extern “C” when including its files:

`extern "C" {`

`#include "gammu/gammu/gammu.h"`

`..............`

`}`

### Global variables

gammu.c uses the following global variables, I recommend their adoption:

Variable | Details
GSM_StateMachine s | Basic layer to the phone connection
GSM_Phone_Functions *Phone | Interface to the phone (see phone functions above)
static CFG_Header *cfg | Configuration settings retrieved from gammurc
GSM_Error error | Current errorlevel. Important values are GE_NONE=1 and GE_NOTIMPLEMENTED=19

### Basic procedure

In order to work with Gammu, follow the following procedure observed in gammu.c:

Step | Description | Command
1 | (optional): Find and parse out the “gammurc” configuration file | cfg=CFG_FindGammuRC();
2 | Load configuration settings | CFG_ReadConfig(cfg, &s.Config);
3 | Connect to phone | GSM_Init(false);
....
4 | Interface phone | For example: error=Phone->GetRingtone(&s, &ringtonebin,0);
....
5 | Terminate connection | GSM_Terminate();

Note: The functions GSM_Init and GSM_Terminate are located in gammu.c.

### Working without a gammurc

When Gammu can’t find the gammurc, it will fall back to its defaults which are entered in the function CFG_ReadConfig in common/gsmring.c.

### DLL or not?

Starting with release 0.64, there is a DLL version of Gammu included in the distribution. As of now, it mostly acts as a demonstration on how to use Gammu routines in other environments (Delphi) and encapsulates only a few of its functions, none of the ones I needed (which were functions for ringtone, contact, calendar, wap data access).

Thus, the DLL would have to be adjusted with every new release of Gammu in the same manner as with the current implementation, defying the independent nature of a DLL, so I decided not to use this DLL as a base for now. Still, I assume that the DLL will soon encapsulate all Gammu functions, making it an interesting option for the future.