Source: kalcatel/alcasync/alcatel.h


Annotated List
Files
Globals
Hierarchy
Index
/*
 * alcasync/alcatel.h
 *
 * low level functions for communication with Alcatel One Touch 501 and
 * compatible mobile phone
 *
 * NOTE:
 * This is EXPERIMANTAL implementation of comunication protocol used by
 * Alcatel 501 (probably also any 50x and 70x) mobile phone. This code may
 * destroy your phone, so use it carefully. However whith my phone works this
 * code correctly. This code assumes following conditions:
 *  - no packet is lost
 *  - 0x0F ack doesn't mean anything important
 *  - data will be received as they are expected
 *  - no error will appear in transmission
 *  - all string are given in form that works in mobile and also in C
 *  - all magic numbers mean that, what I thing that they mean ;-)
 *
 * Copyright (c) 2002-2003 by Michal Cihar 
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation; either version 2 of the License, or (at your
 * option) any later version.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
 * more details.
 *
 * In addition to GNU GPL this code may be used also in non GPL programs but
 * if and only if programmer/distributor of that code receives written
 * permission from author of this code.
 *
 */
/* $Id: alcatel.h,v 1.14 2003/05/09 16:52:46 michal Exp $ */

#ifndef ALCATEL_H
#define ALCATEL_H

/* packet types: */
/* used for starting binary connection (must be preceeded by
 * AT+CPROT=16,"V1.0",16 and phone should response to it by CONNECT_ACK) */
#define ALC_CONNECT                 0x0A
/* received when connect suceeded */
#define ALC_CONNECT_ACK             0x0C
/* used for stopping binary connection */
#define ALC_DISCONNECT              0x0D
/* received when binnary connection ends */
#define ALC_DISCONNECT_ACK          0x0E
/* some control ack, I really don't know what should it do, so currently it
 * is just ignored */
#define ALC_CONTROL_ACK             0x0F
/* sending/recieving data */
#define ALC_DATA                    0x02
/* acknowledge to data */
#define ALC_ACK                     0x06

/* synchronisation types (for all functions except alcatel_begin_transfer): */
#define ALC_SYNC_TYPE_CALENDAR      0x64
#define ALC_SYNC_TYPE_TODO          0x68
#define ALC_SYNC_TYPE_CONTACTS      0x6C

/* synchronisation types (for alcatel_begin_transfer): */
#define ALC_SYNC_CALENDAR           0x00
#define ALC_SYNC_TODO               0x02
#define ALC_SYNC_CONTACTS           0x01

/* for reading list of categories (in todo and contacts) */
#define ALC_LIST_TODO_CAT           0x9B
#define ALC_LIST_CONTACTS_CAT       0x96

/* type used for I/O with mobile */
#define alc_type                    unsigned char

/* size of arrays with names */
#define ALC_CONTACTS_FIELDS         25
#define ALC_CALENDAR_FIELDS         22
#define ALC_TODO_FIELDS             10

/* max count of categories (probably is smaller) */
#define ALC_MAX_CATEGORIES          255 /* TODO: this should be examined more exactly */

/* calendar event types */
#define ALC_CALENDAR_APPOINTMENT    0
#define ALC_CALENDAR_BIRTHDAY       2
#define ALC_CALENDAR_CALL           3
#define ALC_CALENDAR_ALARM          4 /* Alarm=Alarm2: when beep */
#define ALC_CALENDAR_DAILY_ALARM    5 /* Alarm: last set???, Alarm2: when beep */
#define ALC_CALENDAR_REPEATING      9

/** types of return values
 */
enum AlcatelFieldType {
    _date,      /* DATE      */
    _time,      /* TIME      */
    _string,    /* char *    */
    _phone,     /* char *    */
    _enum,      /* int       */
    _bool,      /* int       */
    _int,       /* int       */
    _byte       /* int       */
};

/** structure to store data from alcatel
 */
struct AlcatelFieldStruct {
    /** type of data
      */
    AlcatelFieldType type;
    /** pointer to data of type determined by type field
      */
    void *data;
};

/** structure to store date
 */
struct AlcatelDateStruct {
    int day;
    int month;
    int year;
};

/** structure to store time
 */
struct AlcatelTimeStruct {
    int hour;
    int minute;
    int second;
};

#define ALC_ERR_DATA    -1;

/** returned error codes are taken directly from mobile (>0) or generated by
 * alcasync (<0), majority of mobile error codes are unknown, but here are
 * few with ther probably meaning:
 *
 *  0x00 = ok, operation suceeded
 *
 *  0x10 = calendar busy - this you will get when attempt to select sync type
 *          as calendar or todo and user has opened calendar or todo directly
 *          on mobile (in this case calendar and todo are treated as same
 *          "object", so if you try to open todo and user lists in calendar
 *          you will get this failure)
 *  0x14 = bad data - this library has probably made data that do not conform
 *          protocol that is used, try to find out which packet was send
 *          before and what action failed and they either try to find error
 *          or try to contact author to help you with it
 *  0x13 = closing of nonexistent session ???
 *  0x0C = bad dbid/item id
 *  0x2A = nonexistant field/item id
 *  0x2F = closing session when no open
 *  0x11 = bad list id 
 *
 *  other values are also possible...
 */
extern int alcatel_errno;

/** initialises binary mode
 */
bool alcatel_init(void);

/** ends binary mode
 */
bool alcatel_done(void);

/** send packet of type type, if type = ACL_DATA then data are read from data
 * (length len, \0 is not treated as end) */
void alcatel_send_packet(alc_type type, alc_type *data, alc_type len);

/** receives ack from mobile
 */
alc_type *alcatel_recv_ack(alc_type type);

/** receives data from mobile
 *
 * @param if true, packet is acknowledged
 */
alc_type *alcatel_recv_packet(bool ack);
    
/** attach to mobile, this must be used before any action
 */
bool alcatel_attach(void);

/** Detach from mobile, must be used before done.
 * This causes message about synchronistaion disppears on phone display.
 */
bool alcatel_detach(void);

/** Start synchronisation session.
 * This causes message about synchronistaion appears on phone display.
 */
bool alcatel_start_session(void);

/** close synchronisation session
 */
bool alcatel_close_session(alc_type type);

/** select synchronisation type
 * returns error code from phone (see above)
  */
bool alcatel_select_type(alc_type type);

/** Start transfer of selected type, do NOT use here ALC_SYNC_TYPE_* use the
 * ALC_SYNC_name instead. */
bool alcatel_begin_transfer(alc_type type);

/** Returns array with ids of items of currently selected type. First item in
 * array contains length of it. */
int *alcatel_get_ids(alc_type type);

/** Returns array with field ids for selected item of currently selected type.
 * First item in array contains length of it. */
int *alcatel_get_fields(alc_type type, int item);

/** Returns array with data from selected field. First item in array contains
 * length of it. Following containg raw data as received from mobile, use 
 * decode_field_value to get them more readable. */
alc_type *alcatel_get_field_value(alc_type type, int item, int field);

/** Decodes raw field value to FIELD structure.
 */
AlcatelFieldStruct *decode_field_value(alc_type *buffer);

/** Returns array with ids of categories. First item in array contains length
 * of it. */
int *alcatel_get_obj_list(alc_type type, alc_type list);

/** Returns name for selected category.
 */
char *alcatel_get_obj_list_item(alc_type type, alc_type list, int item);

/** Creates category.
 */
int alcatel_create_obj_list_item(alc_type type, alc_type list, const char *item);

/** Commits changes.
 */
int alcatel_commit(alc_type type);

/** Delete all categories.
 */
bool alcatel_del_obj_list_items(alc_type type, alc_type list);

/** Updates field
 */
bool alcatel_update_field(alc_type type, int item, int field, AlcatelFieldStruct *data);

/** Creates field, after creating all fields for new record call @ref sync_commit
 */
bool alcatel_create_field(alc_type type, int field, AlcatelFieldStruct *data);

/** Deletes item
 */
bool alcatel_delete_item(alc_type type, int item);

/** Deletes field
 */
bool alcatel_delete_field(alc_type type, int item, int field);

#endif

Generated by: michal on quirk.cic on Fri May 9 19:34:14 2003, using kdoc 2.0a54.