Types and Constants

alpha version, October 2000

const TUid KXApplicationUid;

The current application UID. Quite probably you won't want to use it explicitly, and all the implicit usage is cared for properly by the framework. Don't use it unless you really need to; this API is deprecated and there will be better support for this in the XApplication framework soon.

XAPPNAME

A macro, defined as a plain C string, containing the current application name. Don't use it unless you really need to; this API is deprecated and there will be better support for this in the XApplication framework soon.

typedef TBool BOOL;
#define YES ETrue
#define NO EFalse

This way God meant the boolean type and values to be called! Though a minor thing, even for an experienced programmer it is ways more intelligible just to check if YES or NO, instead of some highly philosophical wondering whether true (or even ETrue) or false...

Nevertheless, as the typedef and #defines clearly suggest, there is no harm--but the less comprehensibility--of using the Epoc types and constants directly.

typedef CXObject *id;
typedef CXObjectClassClass *Class;

An "any object" type id, and "any class" type Class. They should in principle be defined as void* both, but that is quite impossible in the C++ with its fatuous type checks. For the same reason, you generally have to cast explicitly even the id or Class whenever you want to use them.

#define nil NULL
#define Nil nil

"No object" is pronounced nil, and "no class" is pronounced Nil. Of course, there is no harm--but the less comprehensibility--of using the plain old NULL anywhere.

#define XNUM2OBJ(num) (CXStringClass->stringWith(@d"%d",(int)(num)))
#define XOBJ2NUM(obj) ((obj)->intValue())

Till there is a proper CXNumber class, these two macros can be used to convert numeric (integral) values like int, unsigned, id (!!!) or BOOL to and from objects. It is sometimes needed in case you want to store these plain-C values into the object containers like CXArray or CXDictionary:

int aNumber;
CXArray *anArray;
...
[anArray addObject:XNUM2OBJ(aNumber)];
...
aNumber=XOBJ2NUM([anArraylastObject]);

typedef double XTimeInterval;
#define X_TI_MICROSECONDS(ti) (TTimeIntervalMicroSeconds32((int)ti*1e6))

In some near future, we will support a full-featured CXDate class. Till then, there is at least a date type which represents a time interval: quite naturally, it is a real number, containing the number of seconds--a half of second is then just 0.5, and so on. The macro X_TI_MICROSECONDS converts this value to the microsecond value used by the Epoc API.

typedef struct _XRange {
    unsigned int location;
    unsigned int length;
} XRange;

The XRange type is the standard XSdk way of specifying any from-to quantity. The values are named descriptively, so there should be no confusion using them. Ranges are used so often it is worth to define them as XFoundation generic types here.

XRange XMakeRange(unsigned int loc, unsigned int len);
unsigned int XMaxRange(XRange range);
BOOL XLocationInRange(unsigned int loc, XRange range);
BOOL XEqualRanges(XRange range1, XRange range2);

These few range service routines can be used anywhere to simplify using of ranges. The first one makes a new range (a static struct constructor might be used instead, but struct constructors are not portable well, and besides, the XMakeRange is much more intelligible). Analogically for the remaining services: the XMaxRange just adds the length to the location, and the XLocationInRange and XEqualRange perform primitive tests (hopefully it is clear which ones!).

The XLog service is available. It has a printf-like arguments: the first one (can be either a CXString or an Epoc descriptor) is a format, the following are defined by '%' fields in the format string. The format string can contain "%@", just like the stringWith.

There is a support for different log levels and targets:

• the log target can be either a named file, or the RDebug::Print, or nil (no logs at all); we are endeavoring to support a TCP/IP log targets soon
• there are 16 different log levels (see below), each of them can be switched individually to
  1. be ignored
  2. be logged to the current target
  3. be shown using the User::InfoPrint Epoc service
  4. be both logged and shown

The log levels are as follows:

(*) Temporarily, the XSdk frameworks sometimes logs into the level X. This will change in future XSdk releases.
(**) Currently unsupported, for with the current implementation it was too slow. Will be revived as soon as we succeed to find a way how to workaround the Epoc's lack of global variables faster than via the "thread local storage".

The log target and levels can be set either statically or dynamically. As for the static setting, a file "log.level" (placed in the same folder as the XFoundation.dll library, ie. normally in /System/Libs) is read in, and its contents is presumed to contain:

• levels, where each level is specified by an appropriate character ('X' or '0' for 0, '1'-'9','a'-'f');
• if the character is followed by:
  • '-': the level is ignored (the same applies for non-mentioned levels);
  • '+' or nothing: the level is logged to target (if any);
  • '^': the level is InfoPrinted;
  • '*': the level is both shown and InfoPrinted.
• after all the level characters:
  • if nothing follows, the target is RDebug::Print;
  • if " +" follows, the target is RDebug::Print as well;
  • if " -" follows, the target is nil;
  • if " <filename>" follows, the target is the named file.

Dynamic setting is plain: a log with a prefix of zero can contain the very same string as described above (or an empty string to re-read defaults from the log.level file). It is even possible to get the current setting: if a log with prefix zero/zero is used, the method will return a HBufC of current settings (caller has to deallocate it), even with the start of 0 to allow to use it for change at once.

Copyright © 1999-2000 X.soft, all rights reserved