411 lines
12 KiB
411 lines
12 KiB
#ifndef _KPILOT_PILOT_H
|
|
#define _KPILOT_PILOT_H
|
|
/* KPilot
|
|
**
|
|
** Copyright (C) 1998-2001 by Dan Pilone
|
|
** Copyright (C) 2003-2004 Reinhold Kainhofer <reinhold@kainhofer.com>
|
|
** Copyright (C) 2003-2006 Adriaan de Groot <groot@kde.org>
|
|
**
|
|
*/
|
|
|
|
/*
|
|
** This program is free software; you can redistribute it and/or modify
|
|
** it under the terms of the GNU Lesser General Public License as published by
|
|
** the Free Software Foundation; either version 2.1 of the License, or
|
|
** (at your option) any later version.
|
|
**
|
|
** This program 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 Lesser General Public License for more details.
|
|
**
|
|
** You should have received a copy of the GNU Lesser General Public License
|
|
** along with this program in a file called COPYING; if not, write to
|
|
** the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
|
|
** MA 02110-1301, USA.
|
|
*/
|
|
|
|
/*
|
|
** Bug reports and questions can be sent to kde-pim@kde.org
|
|
*/
|
|
|
|
#include <sys/types.h>
|
|
|
|
#include <pi-appinfo.h>
|
|
#include <pi-buffer.h>
|
|
#include <pi-dlp.h>
|
|
|
|
#include <tqstring.h>
|
|
#include <tqstringlist.h>
|
|
#include <tqvaluelist.h>
|
|
|
|
#include "pilotLinkVersion.h"
|
|
|
|
|
|
/** @file
|
|
* These are some base structures that reside on the
|
|
* handheld device -- strings and binary data.
|
|
*/
|
|
|
|
class PilotDatabase; // A database
|
|
class PilotRecord; // ... has records
|
|
class PilotCategoryInfo; // ... and category information
|
|
|
|
#define MIN(X, Y) ((X) < (Y) ? (X) : (Y))
|
|
|
|
/**
|
|
* The Pilot namespace holds constants that are global for
|
|
* the handheld data structures. Also contains some global
|
|
* functions that deal with pilot-link structures as well
|
|
* as mapping user-visible strings from UTF8 (KDE side) to
|
|
* the encoding used on the handheld.
|
|
*/
|
|
namespace Pilot KDE_EXPORT
|
|
{
|
|
/** Maximum size of an AppInfo block, taken roughly from the pilot-link source. */
|
|
static const int MAX_APPINFO_SIZE=8192;
|
|
|
|
/** Maximum number of categories the handheld has */
|
|
static const unsigned int CATEGORY_COUNT=16;
|
|
|
|
/** Maximum size of a category label */
|
|
static const unsigned int CATEGORY_SIZE=16;
|
|
|
|
/** Category number for unfiled records */
|
|
static const int Unfiled = 0;
|
|
|
|
/** Maximum size (in bytes) of a record's data */
|
|
static const int MAX_RECORD_SIZE = 65535;
|
|
|
|
typedef TQValueList<recordid_t> RecordIDList;
|
|
|
|
/** Static translation function that maps handheld native (8 bit,
|
|
* usually latin1 but sometimes someting else) encoded data to
|
|
* a Unicode string. Converts the @p len characters in @p c
|
|
* to a Unicode string.
|
|
*/
|
|
TQString fromPilot( const char *c, int len );
|
|
|
|
/** Static translation function mapping a NUL-terminated
|
|
* string from the handheld's encoding to UTF-8.
|
|
* @param c the NUL-terminated string to decode
|
|
* @return TQString (UTF-8) value of @p c
|
|
* @note NUL-terminated strings are rare on the handheld.
|
|
*/
|
|
TQString fromPilot( const char *c );
|
|
|
|
/** Static translation function that maps a TQString onto the
|
|
* native 8 bit encoding of the handheld. Writes the result into
|
|
* the buffer @p buf which has size @p len. Returns the length
|
|
* of the result. Zero-fills the buffer as needed.
|
|
*/
|
|
int toPilot( const TQString &s, char *buf, int len);
|
|
int toPilot( const TQString &s, unsigned char *buf, int len);
|
|
|
|
/** Static translation function that maps a TQString onto the
|
|
* native 8 bit encoding of the handheld.
|
|
*
|
|
* @param s String to encode
|
|
* @return Encoded string in a TQCString
|
|
*/
|
|
TQCString toPilot( const TQString &s );
|
|
|
|
/** Create a codec for translating handheld native 8 bit to Unicode,
|
|
* using the given codec @p name -- this will often be latin1, but
|
|
* might be something else for, say, Russian-language Pilots.
|
|
* If @p name is empty, use latin1.
|
|
*
|
|
* @return @c true on success, @c false otherwise
|
|
*/
|
|
bool setupPilotCodec(const TQString &name);
|
|
|
|
/** Returns the name of the codec being used. */
|
|
TQString codecName();
|
|
|
|
/** For debugging, display category names for the given AppInfo
|
|
* structure. Called by dump(). You must pass a valid reference.
|
|
*/
|
|
void dumpCategories(const struct CategoryAppInfo *info);
|
|
|
|
/** Check that a given category number is valid. This
|
|
* restricts the range of integers to [0..CATEGORY_COUNT-1]
|
|
* (i.e. [0..15]) which is what the handheld supports.
|
|
*/
|
|
inline bool validCategory(int c)
|
|
{
|
|
if (c<0)
|
|
{
|
|
return false;
|
|
}
|
|
return ((unsigned int)c<CATEGORY_COUNT);
|
|
}
|
|
|
|
/** Returns the TQString for the requested category @p i
|
|
* in the category structure @p info. Returns @c TQString()
|
|
* on error (bad pointer or bad category number). May also
|
|
* return @c TQString() if the category name is empty.
|
|
*/
|
|
inline TQString categoryName(const struct CategoryAppInfo *info, unsigned int i)
|
|
{
|
|
if ( ( i < CATEGORY_COUNT ) && ( info->name[i][0] ) )
|
|
{
|
|
/*
|
|
* Seems to be important that we try to pass the real length here
|
|
* to the codec.
|
|
*/
|
|
return fromPilot( info->name[i], MIN(strlen(info->name[i]),CATEGORY_SIZE) );
|
|
}
|
|
else
|
|
{
|
|
return TQString();
|
|
}
|
|
}
|
|
|
|
/** Returns a list of all the category names available on the
|
|
* handheld. This list is neither ordered nor does it contain
|
|
* all sixteen categories -- empty category names on the
|
|
* handheld are skipped.
|
|
*/
|
|
inline TQStringList categoryNames(const struct CategoryAppInfo *info)
|
|
{
|
|
TQStringList l;
|
|
if (!info)
|
|
{
|
|
return l;
|
|
}
|
|
for (unsigned int i=0; i<CATEGORY_COUNT; ++i)
|
|
{
|
|
TQString s = categoryName(info,i);
|
|
if (!s.isEmpty())
|
|
{
|
|
l.append(s);
|
|
}
|
|
}
|
|
return l;
|
|
}
|
|
|
|
/** Search for the given category @p name in the list
|
|
* of categories; returns the category number. If @p unknownIsUnfiled
|
|
* is true, then map unknown categories to Unfiled instead of returning
|
|
* an error number.
|
|
*
|
|
* @return >=0 is a specific category based on the text-to-
|
|
* category number mapping defined by the Pilot,
|
|
* where 0 is always the 'unfiled' category.
|
|
* @return -1 means unknown category selected when
|
|
* @p unknownIsUnfiled is false.
|
|
* @return 0 == Unfiled means unknown category selected when
|
|
* @p unknownIsUnfiled is true.
|
|
*
|
|
*/
|
|
int findCategory(const struct CategoryAppInfo *info, const TQString &name, bool unknownIsUnfiled);
|
|
|
|
/** Search for the given category @p name in the list
|
|
* of categories; returns the category number. If @p unknownIsUnfiled
|
|
* is @c true, then map unknown categories to Unfiled.
|
|
* If @p unknownIsUnfiled is @c false, insert a @em new
|
|
* category into the structure and return the category
|
|
* number of the new category. Return -1 if (and only if)
|
|
* @p unknownIsUnfiled is false and the category structure
|
|
* is already full.
|
|
*
|
|
* @return >=0 is a specific category based on the text-to-
|
|
* category number mapping defined by the Pilot,
|
|
* where 0 is always the 'unfiled' category.
|
|
* @return 0 Unknown category and @p unknownIsUnfiled is @c true
|
|
* @return -1 means unknown category selected when
|
|
* @p unknownIsUnfiled is false and categories
|
|
* are all full.
|
|
*
|
|
*/
|
|
int insertCategory(struct CategoryAppInfo *info, const TQString &label, bool unknownIsUnfiled);
|
|
|
|
/** The handheld also holds data about each database
|
|
* in a DBInfo structure; check if the database described
|
|
* by this structure is a resource database.
|
|
*/
|
|
static inline bool isResource(struct DBInfo *info)
|
|
{
|
|
return (info->flags & dlpDBFlagResource);
|
|
}
|
|
|
|
|
|
/** @section Binary blob handling
|
|
*
|
|
* For reading and writing binary blobs -- which has to happen to
|
|
* pack data into the format that the handheld needs -- it is important
|
|
* to remember that the handheld has only four data types (as far
|
|
* as I can tell: byte, short (a 2 byte integer), long (a 4 byte integer)
|
|
* and string (NUL terminated). The sizes of the types on the handheld
|
|
* do not necessarily correspond to the sizes of the same-named types
|
|
* on the desktop. This means that 'reading a long' from a binary
|
|
* blob must always be 4 bytes -- not sizeof(long).
|
|
*
|
|
* The following templates help out in manipulating the blobs.
|
|
* Instantiate them with the type @em name you need (char, short, long or
|
|
* char *) and you get a ::size enum specifying the number of bytes
|
|
* (where applicable) and ::append and ::read methods for appending
|
|
* a value of the given type to a pi_buffer_t or reading one from
|
|
* the buffer, respectively.
|
|
*
|
|
* The usage of ::read and ::append is straightforward:
|
|
*
|
|
* append(pi_buffer_t *b, TYPE_VALUE v) Appends the type value @p v to the
|
|
* buffer @p b , extending the buffer as needed.
|
|
*
|
|
* TYPE_VALUE read(pi_buffer_t *b, unsigned int &offset) Read a value from
|
|
* the buffer @p b at position @p offset and return it. The offset value
|
|
* is increased by the number of bytes read from the buffer.
|
|
*
|
|
* To write a binary blob, a sequence of ::append calls constructs the
|
|
* blob. To read the same blob, a sequence of ::read calls with the
|
|
* @em same type parameters is sufficient.
|
|
*
|
|
* The calls may vary a little: the exact interface differs depending
|
|
* on the needs of the type of data to be written to the blob.
|
|
*/
|
|
template<typename t> struct dlp { } ;
|
|
|
|
template<> struct dlp<char>
|
|
{
|
|
enum { size = 1 };
|
|
|
|
static void append(pi_buffer_t *b, char v)
|
|
{
|
|
pi_buffer_append(b,&v,size);
|
|
}
|
|
|
|
/**
|
|
* Returns next byte from buffer or 0 on error (0 is also a
|
|
* valid return value, though).
|
|
*/
|
|
static char read(const pi_buffer_t *b, unsigned int &offset)
|
|
{
|
|
if (offset+size > b->used)
|
|
{
|
|
return 0;
|
|
}
|
|
char c = b->data[offset];
|
|
offset+=size;
|
|
return c;
|
|
}
|
|
} ;
|
|
|
|
template<> struct dlp<short>
|
|
{
|
|
enum { size = 2 };
|
|
|
|
static void append(pi_buffer_t *b, short v)
|
|
{
|
|
char buf[size];
|
|
set_short(buf,v);
|
|
pi_buffer_append(b,buf,size);
|
|
}
|
|
|
|
/**
|
|
* Returns the next short (2 byte) value from the buffer, or
|
|
* -1 on error (which is also a valid return value).
|
|
*/
|
|
static int read(const pi_buffer_t *b, unsigned int &offset)
|
|
{
|
|
if (offset+size > b->used)
|
|
{
|
|
return -1;
|
|
}
|
|
else
|
|
{
|
|
int r = get_short(b->data + offset);
|
|
offset+=size;
|
|
return r;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Overload to read from a data buffer instead of a real pi_buffer;
|
|
* does no bounds checking.
|
|
*/
|
|
static int read(const unsigned char *b, unsigned int &offset)
|
|
{
|
|
int r = get_short(b+offset);
|
|
offset+=size;
|
|
return r;
|
|
}
|
|
} ;
|
|
|
|
template<> struct dlp<long>
|
|
{
|
|
enum { size = 4 };
|
|
|
|
static void append(pi_buffer_t *b, int v)
|
|
{
|
|
char buf[size];
|
|
set_long(buf,v);
|
|
pi_buffer_append(b,buf,size);
|
|
}
|
|
|
|
/**
|
|
* Returns the next long (4 byte) value from the buffer or
|
|
* -1 on error (which is also a valid value).
|
|
*/
|
|
static int read(const pi_buffer_t *b, unsigned int &offset)
|
|
{
|
|
if (offset+size > b->used)
|
|
{
|
|
return -1;
|
|
}
|
|
else
|
|
{
|
|
int r = get_long(b->data + offset);
|
|
offset+=size;
|
|
return r;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Overload to read a long value from a data buffer; does
|
|
* no bounds checking.
|
|
*/
|
|
static int read(const unsigned char *b, unsigned int &offset)
|
|
{
|
|
int r = get_long(b+offset);
|
|
offset+=size;
|
|
return r;
|
|
}
|
|
} ;
|
|
|
|
template<> struct dlp<char *>
|
|
{
|
|
// No size enum, doesn't make sense
|
|
// No append, use pi_buffer_append
|
|
/**
|
|
* Read a fixed-length string from the buffer @p b into data buffer
|
|
* @p v which has size (including terminating NUL) of @p s.
|
|
* Returns the number of bytes read (which will normally be @p s
|
|
* but will be less than @p s on error).
|
|
*/
|
|
static int read(const pi_buffer_t *b,
|
|
unsigned int &offset,
|
|
unsigned char *v,
|
|
size_t s)
|
|
{
|
|
if ( s+offset > b->used )
|
|
{
|
|
s = b->allocated - offset;
|
|
}
|
|
memcpy(v, b->data + offset, s);
|
|
offset+=s;
|
|
return s;
|
|
}
|
|
|
|
/** Overload for signed char. */
|
|
inline static int read(const pi_buffer_t *b, unsigned int &offset, char *v, size_t s)
|
|
{
|
|
return read(b,offset,(unsigned char *)v,s);
|
|
}
|
|
} ;
|
|
|
|
}
|
|
|
|
#endif
|
|
|