Developer's Guide

From GnokiiWiki

Jump to: navigation, search

Contents

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 git repository: 

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

Read Docs/gnokii-hackers-howto for a description of how the library works. See also the other documents in Docs/ and the source of existing libgnokii functions.

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.

Adding new functions to libgnokii

This is a (possibly incomplete) checklist for adding a new function to libgnokii:

  1. if you need to create a new source file:
    1. create a new include file in include/ or in include/gnokii using existing files as a guide
    2. add the new include file to include/Makefile.am or to include/gnokii/Makefile.am as appropriate
    3. add the new include file to include/gnokii.h.in or only the public functions as appropriate
    4. create the new source file in common/
    5. add the new source file to common/Makefile.am and to the files in the win32 directory (see below)
  2. if you DO NOT need to create a new source file:
    1. add the new public functions to include/gnokii.h.in
  3. if you're adding new commands to drivers add a new GN_OP_* enum to gn_operation before GN_OP_Max in include/gnokii/data.h

Changes to win32/ directory

While only the latest Microsoft compiler is supported, the following files should be updated: 

MSVC6/libgnokii.dsp
MSVC8/libgnokii.vcproj
MSVS2005/libgnokii.vcproj
MSVS2008/libgnokii.vcproj

Developing gnokii

Adding a new command to gnokii

This is a (possibly incomplete) checklist for adding a new command to gnokii:

Changes to gnokii/ directory

  1. create the new source file in gnokii/
  2. add the new source file to gnokii/Makefile.am and to the files in the win32 directory (see below)
  3. add a new OPT_* enum in opt_index at the beginning of gnokii/gnokii.c (add the enum value in a comment every 10 lines)
  4. add a line to long_options[] before { 0, 0, 0, 0 } in gnokii/gnokii.c:parse_options()
  5. add a line to gals[] before { 0, 0, 0, 0 } in gnokii/gnokii.c:parse_options()
  6. add a "case" with a call to the appropriate function in the appropriate switch in gnokii/gnokii.c:parse_options()
  7. add a call to the appropriate function in the new source file to display usage in gnokii/gnokii.c:usage() and its prototype in gnokii/gnokii-app.h

Changes to win32/ directory

While only the latest Microsoft compiler is supported, the following files should be updated: 

MSVC6/gnokii.dsp
MSVC8/gnokii.vcproj
MSVS2005/gnokii.vcproj
MSVS2008/gnokii.vcproj

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.

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, but not everything that gnokii supports (see the README for details). Note that the easier solution for handling SMS from PHP is using smsd with the file module.

This extension has been tested with PHP 4 and with PHP 5.

Sources for current version are available from gnokii-extras git module: 

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

You can find information about older versions of phpgnokii at Daniele's site.

RUBY

Thyagarajan Shanmugham written a demonstration of ruby bindings for libgnokii. You can find it at http://github.com/thyagarajan/rubynokii/wikis/home

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:


Browse the sources of all those programs (and some more) with a WWW interface:


The following examples use version 3 of libgnokii:


The following examples use version 2 of libgnokii:

Error Codes

NumberConstantDescription
0GN_ERR_NONENo error.
1GN_ERR_FAILEDCommand failed.
2GN_ERR_UNKNOWNMODELModel specified isn't known/supported.
3GN_ERR_INVALIDSECURITYCODEInvalid Security code.
4GN_ERR_INTERNALERRORProblem occurred internal to model specific code.
5GN_ERR_NOTIMPLEMENTEDCommand called isn't implemented in model.
6GN_ERR_NOTSUPPORTEDFunction or connection type not supported by the phone or by the phone driver.
7GN_ERR_USERCANCELEDUser aborted the action.
8GN_ERR_UNKNOWNUnknown error - well better than nothing!!
9GN_ERR_MEMORYFULLThe specified memory is full.
10GN_ERR_NOLINKCouldn't establish link with phone.
11GN_ERR_TIMEOUTCommand timed out.
12GN_ERR_TRYAGAINTry again.
13GN_ERR_WAITINGWaiting for the next part of the message.
14GN_ERR_NOTREADYDevice not ready.
15GN_ERR_BUSYCommand is still being executed.
16GN_ERR_INVALIDLOCATIONThe given memory location is invalid.
17GN_ERR_INVALIDMEMORYTYPEInvalid type of memory.
18GN_ERR_EMPTYLOCATIONThe given location is empty.
19GN_ERR_ENTRYTOOLONGThe given entry is too long.
20GN_ERR_WRONGDATAFORMATData format is not valid.
21GN_ERR_INVALIDSIZEWrong size of the object.
22GN_ERR_LINEBUSYOutgoing call requested reported line busy.
23GN_ERR_NOCARRIERNo Carrier error during data call setup?
24GN_ERR_UNHANDLEDFRAMEThe current frame isn't handled by the incoming function.
25GN_ERR_UNSOLICITEDUnsolicited message received.
26GN_ERR_NONEWCBRECEIVEDAttempt to read CB when no new CB received.
27GN_ERR_SIMPROBLEMSIM card missing or damaged.
28GN_ERR_CODEREQUIREDPIN or PUK code required.
29GN_ERR_NOTAVAILABLEThe requested information is not available.
30GN_ERR_NOCONFIGConfig file cannot be read.
31GN_ERR_NOPHONEEither global or given phone section cannot be found.
32GN_ERR_NOLOGIncorrect logging section configuration.
33GN_ERR_NOMODELNo phone model specified in the config file.
34GN_ERR_NOPORTNo port specified in the config file.
35GN_ERR_NOCONNECTIONNo connection type specified in the config file.
36GN_ERR_ASYNCThe actual response will be sent asynchronously.

Related pages

Retrieved from "http://wiki.gnokii.org/index.php/Developer%27s_Guide"
Personal tools