Developer's Guide

From GnokiiWiki

1 Developing the library
2 Developing your programs
3 Other programming languages bindings
- 3.1 Perl
- 3.2 PHP
4 Bugs
5 Examples
6 Error Codes
7 Related pages

Developing the library

You can help adding support for new phones or new functions, but first read the Roadmap and join the mailing lists to avoid duplicate efforts.

Get the sources from the CVS repository, see CVS Access to gnokii source.

Read Docs/gnokii-hackers-howto for a description of how the library works.

Read the gnokii Changelog to know the latest changes in the code base and subscribe to the gnokii users mailing list and the gnokii commit mailing list and join the #gnokii IRC channel at irc.freenode.net. See gnokii support page for other details.

Developing your programs

For a quick hack you can add your code to foogle() in gnokii/gnokii.c. Before trying to use functions that communicate with the phone remember to call businit(): it will connect to the phone and register busterminate() for you with atexit().

Even if libgnokii is already installed you must get the sources (see above) to use the include files. From version 0.6.20 to 0.6.22 the make install target doesn't install the development files, you need to use make install-devel instead.

You just need to include one file that in turn includes all other files.

#include <gnokii.h>

You need to link your program with libgnokii:
gcc -Wall -o foo foo.c `pkg-config --libs gnokii`

Read the gnokii Changelog to know the latest changes in the code base and subscribe to gnokii mailing list, see gnokii support page for details on how to join the mailing list.

Sample programs written in C are available at Gnokii-extras

Other programming languages bindings

Perl

There is a perl module available for gnokii. It gives access to some of the public libgnokii routines from a perl-program. It is intended for application developers who want to use their favorite language in interfacing the phone data with databases, ldap-directories and (in the future) different calendar applications. It is written by Konstantin Agouros and support starts with revision 0.2.6-pre3 of gnokii.

The homepage of this module is http://www.agouros.de/gnokii

Please note that Perl binding has not been updated for some time and may not work with current libgnokii.

A perl module called Gnokiismsd.pm for the SMS::Send module which allows easy sending via the mysql part of smsd.

PHP

Daniele Forsi prepared PHP bindings for libgnokii. It should be mostly up-to-date and supports most of the useful things that you might use from a webpage.

You can find more information about phpgnokii at Daniele's site.

Bugs

Read instructions on the bug tracking system in gnokii support page, paragraph Bugzilla and other.

Examples

The main programs use almost all library functions and therefore are the biggest examples available:

The following utilities may clarify usage of some functions in a more concise way:

ppm2nokia (in gnokii-extras/snippets/logo/)
sendsms (in gnokii/utils/)
todologo (in gnokii-extras/snippets/logo/)
waitcall (in gnokii-extras/snippets/monitor/)

Browse the sources of all those programs (and some more) with the WWW interface to the CVS repository or use a CVS client.

The following examples use version 3 of libgnokii:

dial a voice call by Daniele Forsi
get battery level by Daniele Forsi

The following examples use version 2 of libgnokii:

libgnokii example by BORBELY Zoltan.
libgnokii example by Pawel Kot
libgnokii example by Daniele Forsi

Error Codes

Number	Constant	Description
0	GN_ERR_NONE	No error.
1	GN_ERR_FAILED	Command failed.
2	GN_ERR_UNKNOWNMODEL	Model specified isn't known/supported.
3	GN_ERR_INVALIDSECURITYCODE	Invalid Security code.
4	GN_ERR_INTERNALERROR	Problem occurred internal to model specific code.
5	GN_ERR_NOTIMPLEMENTED	Command called isn't implemented in model.
6	GN_ERR_NOTSUPPORTED	Function or connection type not supported by the phone or by the phone driver.
7	GN_ERR_USERCANCELED	User aborted the action.
8	GN_ERR_UNKNOWN	Unknown error - well better than nothing!!
9	GN_ERR_MEMORYFULL	The specified memory is full.
10	GN_ERR_NOLINK	Couldn't establish link with phone.
11	GN_ERR_TIMEOUT	Command timed out.
12	GN_ERR_TRYAGAIN	Try again.
13	GN_ERR_WAITING	Waiting for the next part of the message.
14	GN_ERR_NOTREADY	Device not ready.
15	GN_ERR_BUSY	Command is still being executed.
16	GN_ERR_INVALIDLOCATION	The given memory location is invalid.
17	GN_ERR_INVALIDMEMORYTYPE	Invalid type of memory.
18	GN_ERR_EMPTYLOCATION	The given location is empty.
19	GN_ERR_ENTRYTOOLONG	The given entry is too long.
20	GN_ERR_WRONGDATAFORMAT	Data format is not valid.
21	GN_ERR_INVALIDSIZE	Wrong size of the object.
22	GN_ERR_LINEBUSY	Outgoing call requested reported line busy.
23	GN_ERR_NOCARRIER	No Carrier error during data call setup?
24	GN_ERR_UNHANDLEDFRAME	The current frame isn't handled by the incoming function.
25	GN_ERR_UNSOLICITED	Unsolicited message received.
26	GN_ERR_NONEWCBRECEIVED	Attempt to read CB when no new CB received.
27	GN_ERR_SIMPROBLEM	SIM card missing or damaged.
28	GN_ERR_CODEREQUIRED	PIN or PUK code required.
29	GN_ERR_NOTAVAILABLE	The requested information is not available.
30	GN_ERR_NOCONFIG	Config file cannot be read.
31	GN_ERR_NOPHONE	Either global or given phone section cannot be found.
32	GN_ERR_NOLOG	Incorrect logging section configuration.
33	GN_ERR_NOMODEL	No phone model specified in the config file.
34	GN_ERR_NOPORT	No port specified in the config file.
35	GN_ERR_NOCONNECTION	No connection type specified in the config file.
36	GN_ERR_ASYNC	The actual response will be sent asynchronously.