Module Gammu

module Gammu: sig .. end
Interface to the gammu library (libGammu) to manage data in your cell phone such as contacts, calendar or messages.

NOTE: Strings used by libGammu often have a maximum allowed length. Strings too long will be trimmed before being passed to libGammu (caml Strings remain 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 (*Can not 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 runnig.*)
| NOSERVICE (*Service setup is missing.*)
| BUSY (*Command failed. Try again.*)
| COULDNT_CONNECT (*Can not connect to server.*)
| COULDNT_RESOLVE (*Can not resolve host name.*)
| GETTING_SMSC (*Failed to get SMSC number from phone.*)
| 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.*)
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
| ARK3116FBUS2
| FBUS2PL2303
| AT
val get_debug : t ->
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.
path : Path to gettext translation. If not set, compiled in default is used.
val make : unit -> t
Make a new clean state machine.
val get_config : t -> int -> 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, -1 for the currently used one.
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 -> config
remove_config s remove the top configuration from the config stack of s.
val length_config : t -> int
Returns length of the configuration stack of the state machine. i.e the number of active configurations.
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.
path : force the use of a custom path instead of the autodetected one (default: autodetection is performed).
section : section number of the gammurc file to read. See Gammu.INI.config for details.
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.
Raises UNCONFIGURED if no configuration was set.

log : logging function.
replies : number of replies to wait for on each request (default: 3).
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.
Returns the number of read bytes.
wait_for_reply : whether to wait for some event (default true).

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
Enters security code (PIN, PUK,...).
val get_security_status : t -> security_code_type
Queries 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.


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.


module SMS: sig .. end
SMS messages manipulation.


module Call: sig .. end
Call entries manipulation.


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.
enable : whether to enable notifications or not. (default = true)
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 -> ( -> unit) -> unit
incoming_call s f register f as callback function in the event of incoming call.
enable : whether to enable notifications or not. (default = true)
val enable_incoming_call : t -> bool -> unit
enable_incoming_call t enable enable incoming call events or not, according to enable.