diff options
Diffstat (limited to 'kpilot/lib/pilot.h')
| -rw-r--r-- | kpilot/lib/pilot.h | 410 |
1 files changed, 0 insertions, 410 deletions
diff --git a/kpilot/lib/pilot.h b/kpilot/lib/pilot.h deleted file mode 100644 index 3ac2918bd..000000000 --- a/kpilot/lib/pilot.h +++ /dev/null @@ -1,410 +0,0 @@ -#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 -{ - /** 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 QCString - */ - 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::null - * on error (bad pointer or bad category number). May also - * return @c TQString::null 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::null; - } - } - - /** 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 - |