Module Gammu

Interface to the gammu library (libGammu) to manage data in your cell phone such as contacts, calendar and messages.

NOTE: Strings used by libGammu often have a maximum allowed length. Strings too long will be trimmed before being passed to libGammu (this library considers OCaml strings as immutable).

NOTE: This library is not thread safe.

Error handling

type error =
| DEVICEOPENERROR

(** Error during opening device *)

| DEVICELOCKED

(** Device locked *)

| DEVICENOTEXIST

(** Device does not exist *)

| DEVICEBUSY

(** Device is busy *)

| DEVICENOPERMISSION

(** No permissions to open device *)

| DEVICENODRIVER

(** No driver installed for a device *)

| DEVICENOTWORK

(** Device doesn't seem to be working *)

| DEVICEDTRRTSERROR

(** Error during setting DTR/RTS in device *)

| DEVICECHANGESPEEDERROR

(** Error during changing speed in device *)

| DEVICEWRITEERROR

(** Error during writing device *)

| DEVICEREADERROR

(** Error during reading device *)

| DEVICEPARITYERROR

(** Can't set parity on device *)

| TIMEOUT

(** Command timed out *)

| FRAMENOTREQUESTED

(** Frame handled, but not requested in this moment *)

| UNKNOWNRESPONSE

(** Response not handled by gammu *)

| UNKNOWNFRAME

(** Frame not handled by gammu *)

| UNKNOWNCONNECTIONTYPESTRING

(** Unknown connection type given by user *)

| UNKNOWNMODELSTRING

(** Unknown model given by user *)

| SOURCENOTAVAILABLE

(** Some functions not compiled in your OS *)

| NOTSUPPORTED

(** Not supported by phone *)

| EMPTY

(** Empty entry or transfer end. *)

| SECURITYERROR

(** Not allowed *)

| INVALIDLOCATION

(** Too high or too low location... *)

| NOTIMPLEMENTED

(** Function not implemented *)

| FULL

(** Memory is full *)

| UNKNOWN

(** Unknown response from phone *)

| CANTOPENFILE

(** Error during opening file *)

| MOREMEMORY

(** More memory required *)

| PERMISSION

(** No permission *)

| EMPTYSMSC

(** SMSC number is empty *)

| INSIDEPHONEMENU

(** Inside phone menu - can't make something *)

| NOTCONNECTED

(** Phone NOT connected - can't make something *)

| WORKINPROGRESS

(** Work in progress *)

| PHONEOFF

(** Phone is disabled and connected to charger *)

| FILENOTSUPPORTED

(** File format not supported by Gammu *)

| BUG

(** Found bug in implementation or phone *)

| CANCELED

(** Action was canceled by user *)

| NEEDANOTHERANSWER

(** Inside Gammu: phone module need to send another answer frame *)

| OTHERCONNECTIONREQUIRED

(** You need other connection for this operation. *)

| WRONGCRC

(** Wrong CRC *)

| INVALIDDATETIME

(** Invalid date/time *)

| MEMORY

(** Phone memory error, maybe it is read only *)

| INVALIDDATA

(** Invalid data given to phone *)

| FILEALREADYEXIST

(** File with specified name already exist *)

| FILENOTEXIST

(** File with specified name doesn't exist *)

| SHOULDBEFOLDER

(** You have to give folder (not file) name *)

| SHOULDBEFILE

(** You have to give file (not folder) name *)

| NOSIM

(** Cannot access SIM card *)

| GNAPPLETWRONG

(** Invalid gnapplet version *)

| FOLDERPART

(** Only part of folders listed *)

| FOLDERNOTEMPTY

(** Folder is not empty *)

| DATACONVERTED

(** Data were converted *)

| UNCONFIGURED

(** Gammu is not configured. *)

| WRONGFOLDER

(** Wrong folder selected (eg. for SMS). *)

| PHONE_INTERNAL

(** Internal phone error (phone got crazy). *)

| WRITING_FILE

(** Could not write to a file (on local filesystem). *)

| NONE_SECTION

(** No such section exists. *)

| USING_DEFAULTS

(** Using default values. *)

| CORRUPTED

(** Corrupted data returned by phone. *)

| BADFEATURE

(** Bad feature string. *)

| DISABLED

(** Some functions not compiled in your OS *)

| SPECIFYCHANNEL

(** Bluetooth configuration requires channel option. *)

| NOTRUNNING

(** Service is not running. *)

| NOSERVICE

(** Service setup is missing. *)

| BUSY

(** Command failed. Try again. *)

| COULDNT_CONNECT

(** Cannot connect to server. *)

| COULDNT_RESOLVE

(** Cannot resolve host name. *)

| GETTING_SMSC

(** Failed to get SMSC number from phone. *)

| ABORTED

(** Operation aborted. *)

| INSTALL_NOT_FOUND

(** Installation data not found. *)

| READ_ONLY

(** Entry is read only. *)

| NETWORK_ERROR

(** Network error. *)

| INI_KEY_NOT_FOUND

(** Pair section/value not found in INI file. *)

| COULD_NOT_DECODE

(** Decoding SMS Message failed. *)

| INVALID_CONFIG_NUM

(** Invalid config number. *)

Possible errors.

val string_of_error : error ‑> string

string_of_error e returns a textual description of the error e.

exception Error of error

May be raised by any of the functions of this module to indicate an error.

Debugging settings

module Debug : sig ... end

State machine

type t

Value holding information about phone connection (called a "state machine").

type config = {
model : string;

(** Model from config file. Leave it empty for autodetection. Or define a phone model to force the phone model and bypass automatic phone model detection. *)

debug_level : string;

(** Debug level. See Gammu.Debug.set_level for acceptable level strings. *)

device : string;

(** Device name from config file such as "com2" or "/dev/ttyS1". *)

connection : string;

(** Connection type as string *)

sync_time : bool;

(** Synchronize time on startup? *)

lock_device : bool;

(** Lock device ? (Unix, ignored on Windows) *)

debug_file : string;

(** Name of debug file *)

start_info : bool;

(** Display something during start ? *)

use_global_debug_file : bool;

(** Should we use global debug file? *)

text_reminder : string;

(** Text for reminder calendar entry category in local language *)

text_meeting : string;

(** Text for meeting calendar entry category in local language *)

text_call : string;

(** Text for call calendar entry category in local language *)

text_birthday : string;

(** Text for birthday calendar entry category in local language *)

text_memo : string;

(** Text for memo calendar entry category in local language *)

}

Configuration of the state machine.

type connection_type =
| BUS2
| FBUS2
| FBUS2DLR3
| DKU2AT
| DKU2PHONET
| DKU5FBUS2
| ARK3116FBUS2
| FBUS2PL2303
| FBUS2BLUE
| FBUS2IRDA
| PHONETBLUE
| AT
| BLUEGNAPBUS
| IRDAOBEX
| IRDAGNAPBUS
| IRDAAT
| IRDAPHONET
| BLUEFBUS2
| BLUEAT
| BLUEPHONET
| BLUEOBEX
| FBUS2USB
| NONE
val get_debug : t ‑> Debug.info

Gets debug information for state machine.

val init_locales : ?⁠path:string ‑> unit ‑> unit

Initializes locales. This sets up things needed for proper string conversion from local charset as well as initializes gettext based translation. This module is automatically initialized the same way init_locales() would do.

val make : ?⁠section:int ‑> unit ‑> t

Make a new clean state machine. It is automatically configured using load_gammurc. If you want to configure it yourself, use push_config to supersede the configuration with the one of your choice.

val get_config : ?⁠num:int ‑> t ‑> config

get_config s ~num gets gammu configuration from state machine s, where num is the number of the section to read, starting from zero. If not specified, the currently used one is returned.

val push_config : t ‑> config ‑> unit

push_config s cfg push the configuration cfg on top of the configuration stack of s.

Gammu tries each configuration, from the bottom to the top of the stack, in order to connect.

val remove_config : t ‑> unit

remove_config s remove the top configuration from the config stack of s.

val length_config : t ‑> int
val load_gammurc : ?⁠path:string ‑> ?⁠section:int ‑> t ‑> unit

Automaticaly finds the gammurc file (see Gammu.INI.of_gammurc), read it and push the config in the state machine.

val connect : ?⁠log:(string ‑> unit) ‑> ?⁠replies:int ‑> t ‑> unit

Initiates connection.

IMPORTANT: do not forget to call disconnect when done as otherwise the connection may be prematurely terminated. In fact, the problem is that if you have no reference to the state machine left, the GC may free it and by the same time terminate your connection.

val disconnect : t ‑> unit
val is_connected : t ‑> bool
val get_used_connection : t ‑> connection_type
val read_device : ?⁠wait_for_reply:bool ‑> t ‑> int

Attempts to read data from phone. Thus can be used for getting status of incoming events, which would not be found out without polling device.

INI files

module INI : sig ... end

These functions parse ini file and make them available in easily accessible manner.

Security related operations with phone.

type security_code_type =
| SEC_SecurityCode

(** Security code. *)

| SEC_Pin

(** PIN. *)

| SEC_Pin2

(** PIN 2. *)

| SEC_Puk

(** PUK. *)

| SEC_Puk2

(** PUK 2. *)

| SEC_None

(** Code not needed. *)

| SEC_Phone

(** Phone code needed. *)

| SEC_Network

(** Network code needed. *)

Definition of security codes.

val enter_security_code : t ‑> code_type:security_code_type ‑> code:string ‑> unit

Enter security code (PIN, PUK,...).

val get_security_status : t ‑> security_code_type

Query whether some security code needs to be entered.

Informations on the phone

module Info : sig ... end

Informations on the phone.

Date and time

module DateTime : sig ... end

Date and time handling.

Memory

type memory_type =
| ME

(** Internal memory of the mobile equipment *)

| SM

(** SIM card memory *)

| ON

(** Own numbers *)

| DC

(** Dialled calls *)

| RC

(** Received calls *)

| MC

(** Missed calls *)

| MT

(** Combined ME and SIM phonebook *)

| FD

(** Fixed dial *)

| VM

(** Voice mailbox *)

| SL

(** Sent SMS logs *)

| QD

(** Quick dialing choices *)

Defines ID for various phone and SIM memories. Phone modules can translate them to values specific for concrete models. Two letter codes (excluding VM and SL) are from GSM 07.07.

type binary_picture
type entry_type =
| Number_General of string

(** General number. *)

| Number_Mobile of string

(** Mobile number. *)

| Number_Work of string

(** Work number. *)

| Number_Fax of string

(** Fax number. *)

| Number_Home of string

(** Home number. *)

| Number_Pager of string

(** Pager number. *)

| Number_Other of string

(** Other number. *)

| Text_Note of string

(** Note. *)

| Text_Postal of string

(** Complete postal address. *)

| Text_Email of string

(** Email. *)

| Text_Email2 of string
| Text_URL of string

(** URL *)

| Date of DateTime.t

(** Date and time of last call. *)

| Caller_Group of int

(** Caller group. *)

| Text_Name of string

(** Name. *)

| Text_LastName of string

(** Last name. *)

| Text_FirstName of string

(** First name. *)

| Text_Company of string

(** Company. *)

| Text_JobTitle of string

(** Job title. *)

| Category of string option

(** Category. *)

| Private of int

(** Whether entry is private. *)

| Text_StreetAddress of string

(** Street address. *)

| Text_City of string

(** City. *)

| Text_State of string

(** State. *)

| Text_Zip of string

(** Zip code. *)

| Text_Country of string

(** Country. *)

| Text_Custom1 of string

(** Custom information 1. *)

| Text_Custom2 of string

(** Custom information 2. *)

| Text_Custom3 of string

(** Custom information 3. *)

| Text_Custom4 of string

(** Custom information 4. *)

| RingtoneID of int

(** Ringtone ID. *)

| PictureID of int

(** Picture ID. *)

| Text_UserID of string

(** User ID. *)

| CallLength of int

(** Length of call. *)

| Text_LUID of string

(** LUID - Unique Identifier used for synchronisation. *)

| LastModified of DateTime.t

(** Date of last modification. *)

| Text_NickName of string

(** Nick name. *)

| Text_FormalName of string

(** Formal name. *)

| Text_WorkStreetAddress of string

(** Work street address. *)

| Text_WorkCity of string

(** Work city. *)

| Text_WorkState of string

(** Work state. *)

| Text_WorkZip of string

(** Work zip code. *)

| Text_WorkCountry of string

(** Work country. *)

| Text_WorkPostal of string

(** Complete work postal address. *)

| Text_PictureName of string

(** Picture name (on phone filesystem). *)

| PushToTalkID of string

(** Push-to-talk ID. *)

| Number_Messaging of string

(** Favorite messaging number. *)

| Photo of binary_picture

(** Photo. *)

| Number_Mobile_Home of string

(** Home mobile number. *)

| Number_Mobile_Work of string

(** Work mobile number. *)

Type of specific phonebook entry.

type sub_memory_entry = {
entry_type : entry_type;

(** Type of entry, with data. *)

voice_tag : int;

(** Voice dialling tag. *)

sms_list : int array;
call_length : int;
add_error : error;

(** During adding SubEntry Gammu can return here info, if it was done OK. *)

}

One value of phonebook memory entry.

type memory_entry = {
memory_type : memory_type;

(** Used memory for phonebook entry. *)

location : int;

(** Used location for phonebook entry. *)

entries : sub_memory_entry array;

(** Values of SubEntries. *)

}

Value for saving phonebook entries.

Messages

module SMS : sig ... end

SMS messages manipulation.

Calls

module Call : sig ... end

Call entries manipulation.

Events

val incoming_sms : ?⁠enable:bool ‑> t ‑> (SMS.message ‑> unit) ‑> unit

incoming_sms s f register f as callback function in the event of an incoming SMS.

val enable_incoming_sms : t ‑> bool ‑> unit

enable_incoming_sms t enable enable incoming sms events or not, according to enable.

val incoming_call : ?⁠enable:bool ‑> t ‑> (Call.call ‑> unit) ‑> unit

incoming_call s f register f as callback function in the event of incoming call.

val enable_incoming_call : t ‑> bool ‑> unit

enable_incoming_call t enable enable incoming call events or not, according to enable.