-
-
16 Sep 2013 07:34:42 UTC
- Distribution: GSM-Gnokii
- Module version: 0.09
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository (git clone)
- Issues
- Testers (0 / 85 / 1)
- Kwalitee
Bus factor: 1- % Coverage
- License: perl_5
- Perl: v5.8.4
- Activity
24 month- Tools
- Download (80.05KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- Carp
- Data::Peek
- DynaLoader
- JSON
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
Take me over?
The maintainer of this distribution is looking for someone to take over! If you're interested then please contact them via email.- NAME
- SYNOPSIS
- DESCRIPTION
- MEMORYTYPES
- PARAMETERS AND RETURN VALUES
- METHODS
- new ({ attributes })
- connect
- disconnect
- PrintError (err)
- GetPhonebook (type, start, end)
- WritePhonebookEntry ({ ... })
- GetSpeedDial (number)
- SetSpeedDial (self, memtype, location, number)
- GetDateTime
- SetDateTime (timestamp)
- GetAlarm
- SetAlarm (hour, minute)
- GetCalendarNotes (start, end)
- WriteCalendarNote ({ ... })
- GetTodo (start, end)
- WriteTodo ({ ... })
- DeleteAllTodos
- GetDisplayStatus
- Ping
- GetIMEI
- GetPowerStatus
- GetMemoryStatus
- GetProfiles (start, end)
- GetSecurity
- GetLogo ({ options })
- GetRingtoneList
- GetRingtone (location)
- GetDirTree (memorytype, depth)
- GetDir (memorytype, path, depth)
- GetFile (path)
- GetSMSCenter (start, end)
- GetSMSFolderList
- CreateSMSFolder (name)
- DeleteSMSFolder (name)
- GetSMSStatus
- GetSMS (memorytype, location)
- DeleteSMS (memorytype, location)
- $err = SendSMS ({ options })
- GetRF
- GetNetworkInfo
- GetWapSettings (location)
- WriteWapSetting ({ ... })
- ActivateWapSetting (location)
- GetWapBookmark (location)
- WriteWapBookmark ({ ... })
- DeleteWapBookmark (location)
- GetFileList
- GetFiles
- GetMMS
- version
- OTHER RESOURCES
- WARNINGS AND WARRANTY
- AUTHOR
- COPYRIGHT AND LICENSE
- SEE ALSO
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
is0
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 returnsundef
.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". Thestart
argument is the first entry to retrieve. Counting starts at 1, not 0. Theend
argument may be0
, 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
andnumber
are required, all other fields are optional.If no
location
is given, the location used will be the first after the last used location. Iflocation
is0
, 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: NoneSome fields are either ignored by this module, because they cause the write to fail (e.g.
tel_common
,tel_general
, andtel_none
), or because the gnokii library does not write them (mainly theaddress
andperson
data seems to get lost).On success,
WritePhonbookEntry
returns the location this entry was written to. On failure it returnsundef
.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 eitherME
orSM
,number
is the key number, usually allowed are keys2
through9
,location
is the location in the phonebook of memory typememorytype
. 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 thetime
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
, andMEMO
. 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 intoA:\*
, or"SM"
, which will descend into the SIM cardB:\*
. Descending is limited todepth
levels, where passing0
fordepth
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 of1
, 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
Module Install Instructions
To install GSM::Gnokii, copy and paste the appropriate command in to your terminal.
cpanm GSM::Gnokii
perl -MCPAN -e shell install GSM::Gnokii
For more information on module installation, please visit the detailed CPAN module installation guide.