/ 
GSM-Gnokii-0.09
River stage zero No dependents
++
 / GSM::Gnokii
H.Merijn Brand

NAME

GSM::Gnokii - Perl extension libgnokii

SYNOPSIS

  use GSM::Gnokii;
  
  $gsm = GSM::Gnokii->new ();
  $gsm->connect ();

  my $date_time    = $gsm->GetDateTime ();
  my $memory_state = $gsm->GetMemoryStatus ();
  my $address_book = $gsm->GetPhoneBook ("ME", 1, 0);

DESCRIPTION

GSM::Gnokii is a driver module to interface Perl with libgnokii.

 At the moment there is no active development, as the author is not able
 to connect the old phone to the new laptop anymore. 
 This module has been requested to transfer maint to the libgnokii
 development team.

MEMORYTYPES

The supported memory types are the ones that gnokii supports on the different phone models, notably:

  ME  Internal memory of the mobile equipment
  SM  SIM card memory
  FD  Fixed dial numbers
  ON  Own numbers
  EN  Emergency numbers
  DC  Dialed numbers
  RC  Received calls
  MC  Missed calls
  LD  Last dialed numbers

For SMS, these are likely to be valid:

  IN  SMS Inbox
  OU  SMS Outbox, sent items
  OUS SMS Outbox, items to be sent
  AR  SMS Archive
  DR  SMS Drafts
  TE  SMS Templates
  F1  SMS Folder 1 (..20)

PARAMETERS AND RETURN VALUES

Most data used in below examples is made up and does not necessarily reflect existing values. Values like "..." are indicating "some sort of data, as my phone did not (yet) yield anything sensible to show.

When ranges are requested, if end is 0 or beyond the maximum allowed location index, it is set to the known maximum, like gnokii accepts "end" as range end. If a requested range includes empty slots (like selecting all speed dials where location 4 is not set), the empty slot returns undef.

For methods that return a status $err, the return code in $err is

undef

When undefined, you passed conflicting or illegal options. I this case, it is very likely that $gsm->{ERROR} contains an explanation.

0

All is well: operation completed successfully.

#

Any other value is either the return code from the call was performed, in which case the value of $gsm->{ERROR} should have been set to tell the cause of failure, or it is set to a sensible return code, like the new location of the item that was added. In that case, $gsm->{ERROR} will contain something like "no error / no data".

METHODS

new ({ attributes })

Returns a new instance of GSM::Gnokii. The attributes are optional. If attributes are passed, it should be in an anonymous hash. Unknown attributes are silently ignored.

verbose
  verbose          => 1,

Will show on STDERR the entry point of functions called

connect

Connect to the phone.

disconnect

Disconnects the phone.

PrintError (err)

Prints the string representation of the err value to the current STDERR handle.

GetPhonebook (type, start, end)

Returns a reference to an array of PhoneBook entries. Each entry has been filled with as much as data as available from the entry in the phone.

The type argument reflects the memory type. See "MEMORYTYPES". The start argument is the first entry to retrieve. Counting starts at 1, not 0. The end argument may be 0, meaning "to the end".

An addressbook entry looks somewhat like:

  memorytype       => "ME",
  location         => 38,
  number           => "+31612345678",
  name             => "John Doe",
  caller_group     => "Friends",
  person           => {
    formal_name      => "Sr. J. Doe",
    formal_suffix    => "Zzz",
    given_name       => "John",
    family_name      => "Doe",
    additional_names => "Aldrick",
    },
  address          => {
    postal           => "P.O. Box 123",
    extended_address => "Whereever",
    street           => "Memory Lane 123",
    city             => "Duckstad",
    state_province   => "N/A",
    zipcode          => "1234AA",
    country          => "Verwegistan",
    },
  birthday         => "1961-12-31",
  company          => "Hackers Inc.",
  date             => "1970-01-01",
  ext_group        => 21,
  e_mail           => 'john.doe@some.where.com',
  nickname         => "johnny boy",
  note             => "This entry reflects imaginary data",
  postal_address   => "Camper 23",
  tel_none         => "+31201230000",
  tel_common       => "+31201230001",
  tel_home         => "+31612340002",
  tel_cell         => "+31612340003",
  tel_fax          => "+31201230004",
  tel_work         => "+31201230006",
  tel_general      => "+31201230010",
  url              => "http://www.some.where.com",

WritePhonebookEntry ({ ... })

Write a phonebook entry. The structure of the hash is as described above in GetPhonebook.

The attributes memorytype and number are required, all other fields are optional.

If no location is given, the location used will be the first after the last used location. If location is 0, it will use the first free location.

caller_group is numeric and should be any of: 0: Family 1: VIPs 2: Friends 3: Work 4: Others 5: None

Some fields are either ignored by this module, because they cause the write to fail (e.g. tel_common, tel_general, and tel_none), or because the gnokii library does not write them (mainly the address and person data seems to get lost).

On success, WritePhonbookEntry returns the location this entry was written to. On failure it returns undef.

GetSpeedDial (number)

Returns a reference to a hash with the information needed to get to the number used:

  number           =>  2,
  location         => 23,
  memory           => "ME",

To get the address book entry to the speed dial, use

  my $ab = $gsm->GetPhonebook ("ME", 23, 23);

SetSpeedDial (self, memtype, location, number)

Set the speed dial specified by the arguments. memtype should be either ME or SM, number is the key number, usually allowed are keys 2 through 9, location is the location in the phonebook of memory type memorytype. See GetPhonebook.

GetDateTime

Returns a reference to a hash with two elements, like:

  date             => "2011-01-23 17:22:37",
  timestamp        => 1295799757,

SetDateTime (timestamp)

Set date and time on device. The timestamp is a unix timestamp as returned by the time function.

GetAlarm

Returns a reference to a hash with alarm info, like:

  alarm            => "07:25",
  state            => "off",

SetAlarm (hour, minute)

Set and enable alarm. Hour should be between 0 and 23, Minute between 0 and 59.

GetCalendarNotes (start, end)

Returns a reference to a list of calendar note hashes, like:

  location         => 1,
  date             => "2011-11-11 11:11:11",
  type             => "Meeting",
  text             => "Be there or be fired",
  mlocation        => "Board room",
  alarm            => "2010-10-10 10:10:10",
  recurrence       => "Weekly",
  number           => "+31612345678",

WriteCalendarNote ({ ... })

Set a calendar note, attributes marked with a * are required

  date             => time + 86400,   # * Date and time of note
  text             => "Call John!",   # * Note text
  type             => "call",         #   Note type, defaults to MEMO
  number           => "+31612345678", #   Required for type CALL
  mlocation        => "Board room",   #   Adviced for type MEET
  alarm            => time + 86400,   #   Alarm time
  recurrence       => "Weekly",       #   Recurrence, defaults to NEVER

Valid note types are REMINDER, CALL, MEETING, BIRTHDAY, and MEMO. Type match is done case-ignorant and types may be abbreviated to 4 characters.

Valid recurrence specifications are NEVER, DAILY, WEEKLY, 2WEEKLY, YEARLY. Type match is done case-ignorant and types may be abbreviated to 4 characters.

GetTodo (start, end)

Returns a reference to a list of TODO note hashes, like:

  location         => 1,
  text             => "Finish GSM::Gnokii",
  priority         => "low",

WriteTodo ({ ... })

Write a TODO note. The contents of the hashref should match what GetTodo returns for a fetched TODO entry.

DeleteAllTodos

Will delete all TODO items.

GetDisplayStatus

Returns a reference to a hash with the display status, all boolean, like:

  call_in_progress => 0,
  unknown          => 0,
  unread_SMS       => 0,
  voice_call       => 0,
  fax_call_active  => 0,
  data_call_active => 0,
  keyboard_lock    => 0,
  sms_storage_full => 0,

Ping

Returns availability of the phone or undef if Ping is unimplemented in libgnokii.

GetIMEI

Returns a reference to a hash with the IMEI data, like:

  model            => "RM-274",
  revision         => "V 07.21",
  imei             => "345634563456678",
  manufacturer     => "...",

GetPowerStatus

Returns a reference to a hash with power related information like:

  level            => "42.8571434020996094",
  source           => "battery",

GetMemoryStatus

Returns a reference to a list of memory status entries, like:

  dcfree           =>   236,    # Dialed numbers
  dcused           =>    20,
  enfree           => 12544,    # Emergency numbers
  enused           =>     0,
  fdfree           => 12544,    # Fied-dial numbers
  fdused           =>     0,
  mcfree           =>   493,    # Missed calls
  mcused           =>    19,
  onfree           =>    15,    # Own numbers
  onused           =>     0,
  phonefree        =>  1902,    # Internal phone memory
  phoneused        =>    98,
  rcfree           =>   748,    # Received calls
  rcused           =>    20,
  simfree          =>   250,    # SIM card
  simused          =>     0,

GetProfiles (start, end)

Returns a reference to a list of hashes with profile information, like:

  number           => 1,
  name             => "Tux",
  defaultname      => "Default",
  call_alert       => "Ringing",
  ringtonenumber   => 3,
  volume_level     => "Level 5",
  message_tone     => "Beep once",
  keypad_tone      => "Level 2",
  warning_tone     => "Off",
  vibration        => "On",
  caller_groups    => 2,
  automatic_answer => "Off",

Note that at some models, requesting profile information outside of the known range might cause the phone to power off.

My own phone timed out on all GetProfile requests.

GetSecurity

Returns a reference to a hash with the security information, like:

  status           => "Nothing to enter",
  security_code    => "...",

GetLogo ({ options })

Return a reference to a hash with Logo information, like:

  text             => "Foo",
  type             => "text",
  bitmap           => "...",
  size             => 64,
  height           => 8,
  width            => 8,

Supported options:

  type             => "...",  # text/dealer/op/startup/caller/
                              #  picture/emspicture/emsanimation
  callerindex      => 0,      # required for type => "caller". NYI

GetRingtoneList

Returns a reference to a hash with ringtone list information, like:

  count            =>   1,
  userdef_count    =>  10,
  userdef_location => 231,

GetRingtone (location)

Returns a reference to a hash with ringtone information, like:

  location         => 1,
  length           => 15,
  name             => 'Tones',
  ringtone         => "\002J:UQ\275\271\225\314\004",

GetDirTree (memorytype, depth)

Return a reference to a (recursive) list of folders and files in the phone. The memorytype should be either "ME" for phone memory, which will descend into A:\*, or "SM", which will descend into the SIM card B:\*. Descending is limited to depth levels, where passing 0 for depth means unlimited. It will return a hash reference like:

  dir_size         => 128,
  file_count       => 18,
  memorytype       => "ME",
  path             => "A:\\*",
  tree             => [ ... ]

The tree entry in the hash is a list of entries in the folder, of which each is a reference to a hash with entry information like:

  date             => "2006-01-01 00:00:00",
  file             => undef,
  folder_id        => 0,
  name             => "FIM_punique_id",
  size             => 66,
  type             => "None",

If the entry has a size greater than 0, there might be added a file_id:

  date             => "2005-01-01 12:00:00",
  file             => undef,
  folder_id        => 0,
  id               => "00.00.10.00.01.8e",
  name             => "Flower2.jpg",
  size             => 10203,
  type             => "None",

If the entry is a folder itself, it will be extended with tree info like in the top node:

  date             => "2006-01-01 00:00:00",
  dir_size         => 128,
  file             => undef,
  file_count       => 13,
  folder_id        => 0,
  name             => "predefgallery",
  path             => "A:\\predefgallery\\*",
  size             => 0,
  tree             => [ ... ]

Note that these calls might take a long time with big trees.

GetDir (memorytype, path, depth)

Like GetDirTree, but with a default depth of 1, and a starting point.

GetFile (path)

Fetches a file from the phone. The path should be in phone format, e.g.

  my $h = $gsm->GetFile ("A:\\FIM_fixed_id");

On success, a hashref is returned with two entries

  size             => 8,
  file             => "\1\0\0\0\0\0\3\0",

GetSMSCenter (start, end)

Returns a reference to a list of SMS Center information hashes like:

  id               => 1,
  name             => "KPN",
  defaultname      => -1,
  format           => "Text",
  validity         => "72 hours"
  type             => 145,
  smscnumber       => "+31612345678",
  recipienttype    => 0,
  recipientnumber  => "",

The valid range for start is 1..5.

GetSMSFolderList

Returns a reference to a list of hashes containing SMS Folder info, like:

  location         => 1,
  memorytype       => "IN",
  name             => "SMS Inbox",
  count            => 42,

CreateSMSFolder (name)

Creates an SMS folder.

DeleteSMSFolder (name)

Deletes an SMS folder.

GetSMSStatus

Returns a reference to the SMS status info, like:

  read             => 73,
  unread           =>  0,

GetSMS (memorytype, location)

Returns a reference to a hash with the SMS data, like:

  memorytype       => "IN",
  location         => 3,
  date             => "0000-00-00 00:00:00",
  sender           => "+31612345678",
  smsc             => "",
  smscdate         => "2010-07-12 20:10:35",
  status           => "read",
  text             => "This is fake data, enjoy!",
  timestamp        => -1,

DeleteSMS (memorytype, location)

Deletes the SMS as specified by the arguments.

$err = SendSMS ({ options })

Sends an SMS, attributes marked with a * are required

  destination      => "+31612345678", # * Recipient phone number
  message          => "Hello there",  # * Message text (max 160 characters)
  smscindex        => 1,              #   Index  of the SMS Center to use or
  smscnumber       => "+31612345678", #   Number of the SMS Center to use
  report           => 1,              #   Delivery report (default off )
  eightbit         => 1,              #   Use 8bit data   (default 7bit)
  validity         => 4320,           #   SMS validity in minutes
  animation        => ".....",        #   Animation ...              (NYI)
  ringtone         => ".....",        #   Filename with ringtone ... (NYI)

All other attribute are silently ignored.

GetRF

Returns a reference to a hash with the RF data, like:

  level            => 100,
  unit             =>   5,

GetNetworkInfo

Returns a reference to a hash with the network information, like:

  name             => "KPN",
  countryname      => "Netherlands",
  networkcode      => "204 08",
  cellid           => "b56f",
  lac              => 1127,

GetWapSettings (location)

Returns a reference to a hash with the WAP settings for given location, like:

  location         => 1,
  name             => "Default",
  home             => "http://p3rl.org",
  session          => "Temporary",
  security         => "yes",
  bearer           => "GPRS",
  gsm_data_auth    => "Secure",
  call_type        => "Analog",
  call_speed       => "Automatic",
  number           => 1,
  gsm_data_login   => "Automatic",
  gsm_data_ip      => "10.11.12.13",
  gsm_data_user    => "johndoe",
  gsm_data_pass    => "Secret",
  gprs_connection  => "Always",
  gprs_auth        => "Secure",
  gprs_login       => "Automatic",
  access_point     => "w3_foo",
  gprs_ip          => "14.15.16.17",
  gprs_user        => "johndoe",
  gprs_pass        => "fidelity",
  sms_servicenr    => "+31612345678",
  sms_servernr     => 456,

WriteWapSetting ({ ... })

Write a WAP setting. Content of the hashref is like what GetWapSetting returns.

ActivateWapSetting (location)

Active WAP setting at location location.

GetWapBookmark (location)

Returns a reference to a hash with WAP bookmark information, like:

  location         => 1,
  name             => "perl",
  url              => "http://p3rl.org",

WriteWapBookmark ({ ... })

Write a WAP bookmark. Content of the hashref should match what GetWapBookmark returns.

DeleteWapBookmark (location)

Delete WAP bookmark at location.

GetFileList

NYI.

GetFiles

NYI.

GetMMS

NYI.

version

Returns the version of the module.

OTHER RESOURCES

  Gnokii home:       http://www.gnokii.org

  To get the most recent development branch:

    $ git clone git://git.savannah.nongnu.org/gnokii.git gnokii-git

  To view the most recent changes:

    http://git.savannah.gnu.org/gitweb/?p=gnokii.git;a=summary

  All gnokii projects:

    http://git.savannah.gnu.org/gitweb/?s=gnokii

  GSMI/GSMD::Gnokii: http://www.agouros.de/gnokii/

WARNINGS AND WARRANTY

This module just aims to be a perl API to libgnokii. All operations are done without warranty. Just at own risk. Bugs could exist in this code, as well as in libgnokii code or in the phone software itself.

Some functionality has not been tested as the phones available for testing did not support the methods. Not all phones allow all actions, even basic ones like GetProfile might not be supported on your mobile device.

AUTHOR

H.Merijn Brand

Author of GSMD::Gnokii is Konstantin Agouros. gnokii@agouros.de His code served as a huge inspiration to create this module.

COPYRIGHT AND LICENSE

 Copyright (C) 2011-2013 H.Merijn Brand. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

gnokii(1), GSMI, GSMD::Gnokii