mwiacek.comColorColor | Mobile  
Gammu+ internals
Submitted by marcin on Mon 07-Apr-2008

English article

I will want to document some internals of project here... This page will grow with project...

First of all, let's start to explain what we need to comunicate with phone... The most important is OS driver for medium used for communication (irda, BT, cable). It's external (for example provided by hardware manufacturer) and installed in OS.

We can separate our project into two things:

  • common part (in common directory)
  • client applications (for example command-line version from gplus directory)

Here is general structure. I'm not the best drawer, but it should explain many things:

I didn't connected "various GSM & non GSM functions" with all other blocks (they should be linked), because it would be very difficult to read. As you see, many functions can be used independly from phone. You're not blocked and have freedom in accesing all things from client application

common part

We need three layers:

Name Directory Files Files content
1. Gammu+ driver for medium used for communication (it communicates with OS medium driver). common/device gsmdev.* GSM_Device_Info class for defining various device parameters and GSM_Device class with device API. Used in files in subdirectories.
common/device/serial ser_w32.* driver for serial cables in Windows (it covers USB cables with drivers, which "connects" cable into COM ports)
common/device/irda irda.* driver for infrared in Windows/Linux
common/device/bluetoth blue_w32.* driver for Microsoft stack in Windows (XP SP2 and later)
2. Gammu+ driver for used protocol (it's using medium driver) common/protocol gsmprot.* GSM_Protocol_Info class for defining various protocol parameters and GSM_Protocol class with protocol API. Used in files in subdirectories.
common/protocol/nokia fbus2.* Nokia FBUS2 for cable
common/protocol/nokia phonet.* Nokia PHONET for bluetooth/infrared
3. Gammu+ driver for used phone (it's using protocol driver to send and receive bytes to phone) common/phone gsmphone.* GSM_Phone_Info class for defining various phone models parameters and GSM_Phone class with phone API available for ordinary user. Used in files in subdirectories.
common/phone/nokia nauto.* driver for automatic detecting Nokia phone model and switching to correct phone driver from subdirectories (DCT3 or DCT4S40)
common/phone/nokia ndct34.* functions shared for DCT3 and DCT4S40
common/phone/nokia/dct3 n6110.* phone driver for old DCT3 phones
common/phone/nokia/dct3 n7110.* phone driver for latest DCT3 phones
common/phone/nokia/dct3 ndct3.* functions shared for n6110.* and n7110.*
common/phone/nokia/dct4s40 n6510.*



phone driver for DCT4, TIKU, BB5 phones (Series 40 1.0 - 3.0)

All things above use

Name Directory Files Files content
1. structures, functions for GSM related stuff common/service gsmcal.* calendar
gsmpbk.* phonebook
gsmfiles.* filesystem
gsmmisc.* for all other
common/service/sms for SMS
common/service/backup for backup/restore formats
2. some general functions (can be used with non-GSM projects too) common/misc ini.* INI style files (sections, entries, values)
misc.* for various usefull functions
common/misc/coding coding.* for various encoding functions (encoding/decoding/recoding), they're sometimes are similiar to functions available in some libraries
3. config file cfg config.h

and are joined inside GSM_StateMachine in common/gsmstate.*

When you want to use common part, you have to include:

  • common/gsmstate.h
  • required *.h files from common/service and subdirectories
  • required *.h files from common/misc and subdirectories

Here is diagram showing (planned) structure for the most important functions from common/service:

command line version

It's in the gplus directory - files gplus.* are main and gfiles.*, gsms.* are included

sending messages

Here is diagram, which show the most important things in sending/receiving messages process

All is done in one application thread. We have eliminated various typical bugs like using scheme:

  1. send message
  2. make one receiving and decode received bytes as message

(it's wrong, because sometimes there is required reading bytes from device many times to get full answer).

We handle incoming messages too (for example we don't have problems in situation, when we want to read phonebook and phone inform - SMS message received)

where are differences from Gammu ?

  • GSM_Error is structure now. For example: when you have error code about missed file, structure contains info about file path & name
  • SMS structure doesn't have ID in form folder & location - it's string now (it allows to save file name & path for Series 40 3.0)
  • some API (for example for getting folders for Java) has been moved from client application to common part
  • phone modules have internal cache for filesystem folders info (shared by Java, SMS and many other...)
  • some functions (like for MMS) are much more extended than Gammu versions (they decode more formats)...
  • during restoring phonebook, calendar, notes and other you have concrete info, which subentries were restored (available in Gammu in much more primitive form)...
  • there are put lists (instead of hard coded tables) in much more number of places...
  • some classes for SMS and MMS are orientated for "phisical" content (for example file with MMS), some for "logical" (for example decoded text). You can fill structure with "logical" content (for example text, ringtones,...) and later save it to "phisical" form using the same source...
  • you have GUI created with core. It's always actual

In short word: Gammu+ contains continued and extended Gammu internals modified for better handling modern (Nokia) phones...

what can be improved

Like Michal Čihař notified in November 2006 project internally isn't maybe excellent, but from my point of view removes many Gammu internal issues. It's also good, because it's already written and working. Let's see on Michal's comments now:

  1. "There is no design document, where can developer find how the code is organised and what is supposed to be API" - we started it HERE
  2. "There is no definition of external API. Everything is mixed together in simmilar way as in Gammu" - that's true, that we don't have one central h file; we try to give info about user API HERE (bold and other)
  3. "I don't see reasong for passing pointers (and especially double pointers (eg. DebugInfo) instead of C++ references" - for me differences are partially invisible, help required with implementing...
  4. "Why not using widestring constants instead of converting all using some function?" - some things don't need widestrings
    :: I meant using StringToUnicodeReturn("connection") instead of L"connection". Michal 10:17, 12 November 2006 (GMT)
    :: As I said, I'm not C++ guru. If there is something like this and it's supported both in Linux & Windows, I can use it. THX. Marcin 16:02, 12 November 2006 (GMT)
  5. "Why there are reimplemented lists in backup? All those GSM_Backup_*Entry IMHO can be replaced by list\." - help required
  6. "There is too much malloc used (you should need it very rarely in C++)" - yes, it could be improved, but doesn't affect user visible parts and ...
  7. "Too much reimplementation of standard C library (eg. wcscasecmp vs. UnicodeCaseCmp)" - only few functions reimplemented because aren't available in some OS
    :: But it this case configure should check for such functions and use own only if it is necessary. Michal 10:17, 12 November 2006 (GMT)
    :: Probably yes. But IMHO writing configure script would need more time than writing these few (because we speak about max. 5-6 functions) simple things. Marcin 16:02, 12 November 2006 (GMT)

In 7 points I see 3 REAL problems. Isn't bad...