You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
kpilot/lib/pilotAppInfo.h

217 lines
6.0 KiB

#ifndef _KPILOT_PILOTAPPINFO_H
#define _KPILOT_PILOTAPPINFO_H
/* pilotAppInfo.h KPilot
**
** Copyright (C) 2005-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 "pilotLinkVersion.h"
#include "pilot.h"
#include "pilotDatabase.h"
/**
* A database on the handheld has an "AppInfo" block at the beginning
* with some database-specific information and a common part.
* This base class deals with the common part, the categories.
*
* Most data in the handheld is stored in @em categories ; every
* record in every database, for instance, has a category assigned
* to it (perhaps "Unfiled", but that's just another category).
*
* Every database has a category table assigning labels to the
* categories that exist. There are CATEGORY_COUNT (16) categories
* available for each database; labels may vary per database.
*
* This class encapsulates the basic category table manipulations.
*/
class KDE_EXPORT PilotAppInfoBase
{
protected:
/** Initialize class members after reading header, to alias data elsewhere.
* Only for use by the (derived) template classes below.
*/
void init(struct CategoryAppInfo *c, int len)
{
fC = c;
fLen = len ;
} ;
public:
/** Constructor. This is for use by derived classes (using the template below
* only, and says that the category info in the base class aliases data in
* the derived class. Remember to call init()!
*/
PilotAppInfoBase() : fC(0L), fLen(0), fOwn(false) { } ;
/** Constructor, intended for untyped access to the AppInfo only. This throws
* away everything but the category information. In this variety, the
* CategoryAppInfo structure is owned by the PilotAppInfoBase object.
*/
PilotAppInfoBase(PilotDatabase *d);
/** Destructor. */
virtual ~PilotAppInfoBase();
/** Retrieve the most basic part of the AppInfo block -- the category
* information which is guaranteed to be the first 240-odd bytes of
* a database.
*/
struct CategoryAppInfo *categoryInfo()
{
return fC;
} ;
/** Const version of the above function. */
inline const struct CategoryAppInfo *categoryInfo() const
{
return fC;
} ;
/** Returns the length of the (whole) AppInfo block. */
inline PI_SIZE_T length() const
{
return fLen;
} ;
/** @see findCategory(const TQString &name, bool unknownIsUnfiled, struct CategoryAppInfo *info). */
inline int findCategory(const TQString &name, bool unknownIsUnfiled = false) const
{
return Pilot::findCategory(fC,name,unknownIsUnfiled);
} ;
/** Gets a single category name. Returns TQString::null if there is no
* such category number @p i . */
inline TQString categoryName(unsigned int i) const
{
return Pilot::categoryName(fC,i);
}
/** Sets a category name. @return true if this succeeded. @return false
* on failure, e.g. the index @p i was out of range or the category name
* was invalid. Category names that are too long are truncated to 15 characters.
*/
bool setCategoryName(unsigned int i, const TQString &s);
/** For debugging, display all the category names */
inline void dump() const
{
Pilot::dumpCategories(fC);
};
protected:
struct CategoryAppInfo *fC;
PI_SIZE_T fLen;
bool fOwn;
} ;
/** A template class for reading and interpreting AppInfo blocks;
* the idea is that it handles all the boilerplate code for reading
* the app block, converting it to the right kind, and then unpacking
* it. Template parameters are the type (struct, from pilot-link probably)
* of the interpreted appinfo, and the pack and unpack functions for it
* (again, from pilot-link).
*/
template <typename appinfo,
#if PILOT_LINK_IS(0,12,2)
/* There are additional consts introduced in 0.12.2 */
int(*unpack)(appinfo *, const unsigned char *, PI_SIZE_T),
int(*pack)(const appinfo *, unsigned char *, PI_SIZE_T)
#else
int(*unpack)(appinfo *, unsigned char *, PI_SIZE_T),
int(*pack)(appinfo *, unsigned char *, PI_SIZE_T)
#endif
>
class PilotAppInfo : public PilotAppInfoBase
{
public:
/** Constructor. Read the appinfo from database @p d and
* interpret it.
*/
PilotAppInfo(PilotDatabase *d) : PilotAppInfoBase()
{
int appLen = Pilot::MAX_APPINFO_SIZE;
unsigned char buffer[Pilot::MAX_APPINFO_SIZE];
memset(&fInfo,0,sizeof(fInfo));
if (d && d->isOpen())
{
appLen = d->readAppBlock(buffer,appLen);
(*unpack)(&fInfo, buffer, appLen);
// fInfo is just a struct, so we can point to it anyway.
init(&fInfo.category,appLen);
}
else
{
delete fC;
fC = 0L;
fLen = 0;
init(&fInfo.category,sizeof(fInfo));
}
} ;
PilotAppInfo()
{
memset(&fInfo,0,sizeof(fInfo));
init(&fInfo.category,sizeof(fInfo));
}
/** Write this appinfo block to the database @p d; returns
* the number of bytes written or -1 on failure. This
* function is robust when called with a NULL database @p d.
*/
int writeTo(PilotDatabase *d)
{
unsigned char buffer[Pilot::MAX_APPINFO_SIZE];
if (!d || !d->isOpen())
{
return -1;
}
int appLen = (*pack)(&fInfo, buffer, length());
if (appLen > 0)
{
d->writeAppBlock(buffer,appLen);
}
return appLen;
} ;
/** Returns a (correctly typed) pointer to the interpreted
* appinfo block.
*/
appinfo *info() { return &fInfo; } ;
/** Returns a const (correctly typed) pointer to the interpreted
* appinfo block.
*/
const appinfo *info() const { return &fInfo; } ;
protected:
appinfo fInfo;
} ;
#endif