General

Inside Macintosh: OpenDoc Class Reference / Part 2 - Types and Constants

General
This section describes the general types and constants used widely in OpenDoc.

Numeric Data
The following types represent numeric data.

ODFixed
A 32-bit fixed-point value used to represent noninteger numbers in the range [-32768, 32768). The high 16 bits (including a sign bit) represent the integer part, and the low 16 bits represent a fractional part. In effect, the "binary point" is in the middle of the number.

You can convert an integer to ODFixed by shifting it left 16 bits. You can round an ODFixed value to an integer by adding 0x8000 (0.5) and shifting the result right 16 bits. You can convert between ODFixed and floating-point by multiplying or dividing by 65536.0. You can add and subtract ODFixed values as though they were integers; however, you cannot multiply or divide them directly. The OpenDoc ODMath utility library contains functions for working with the ODFixed type.

On the Mac OS, this type is identical to the Fixed type. The Mac OS has several Toolbox routines, such as FixMul and FixDiv, for doing arithmetic on Fixed values.
ODFloat
A floating-point value; the size of this type is platform-dependent.
ODFract
A 32-bit fixed-point value used to represent noninteger numbers in the range [-2, 2). The high 2 bits (including the sign bit) represent the integer part, and the low 30 bits represent a fractional part.

You can convert an integer to ODFract by shifting it left 30 bits. You can round an ODFract value to an integer by adding 0x20000000 (.5) and shifting the result right 30 bits. You can convert between ODFract and floating-point numbers by multiplying or dividing by a scaling factor of 1073741824.0. You can add and subtract ODFract values as though they were integers; however, you cannot multiply or divide them directly. The OpenDoc ODMath utility library contains functions for working with the ODFract type.

On the Mac OS, this type is identical to the Fract type. The Mac OS has several Toolbox routines, such as FracMul and FracDiv, for doing arithmetic on Fract values.
ODSLong
A signed 32-bit integer value.
ODSShort
A signed 16-bit integer value.

Characters, Strings, and Tokens
The following types and constants represent characters, text strings, and tokens created from strings. Types and constants marked [M] are specific to the Mac OS platform.

ODISOStr
A pointer to an ISO string, that is, a string composed of ASCII characters, terminated by a null character (zero byte). Because the first null character terminates the string, null characters may not be embedded.
ODIText
A platform-specific structure representing a user-visible international text string. The characters in an international text string are represented by 8-bit bytes; thus a total of 256 byte values can be used. In contrast, only the 128 ASCII characters can be used in an ISO string. On the Mac OS, this type is defined as follows:
            struct ODIText {
               ODITextFormat  format;
               ODByteArray    text; 
            };
Field descriptions

format
The format of the text. Currently, kODTraditionalMacText is the only format supported on the Mac OS platform.
text
The text string, represented as an ODByteArray structure (page 877) in the specified format.

In the kODTraditionalMacText format, the buffer of this byte array contains two 16-bit values followed by the raw text. The first 16-bit value is the script code, the second is the language code. The _length field of this byte array indicates the entire length of the buffer in 8-bit bytes; subtract the length of the two codes (4 bytes) to get the number of characters in the text string.
Related constants

kODISO10646_1993BaseEncoding
An 18-bit code indicating the document interchange format of text written out by OpenDoc. This fully decomposed format corresponds to ISO standard 10646-1, 1993; it is the only interchange format for text currently supported by OpenDoc.

When international text is stored in an interchange format, the interchange-format code is stored with the encoded text.
ODITextFormat
A 32-bit value specifying a text format. The only format currently supported on the Mac OS platform is kODTraditionalMacText; more formats may be supported in the future.
Constants of this type

kODTraditionalMacText [M]
The traditional Mac OS international text standard of script code/language code/string.
ODName
A name in international text, of type ODIText (page 875).
ODSByte
A signed 8-bit value, typically used to represent a single character.
ODType
A string of type ODISOStr (page 875) used generically within OpenDoc to represent drag-image types, object types, and value types for storage units, frame presentation types and view types, focus types, and extension types. The constants defined for this data type are described under the sections related to data transfer, storage units, user interface, and extensions.
ODTypeToken
A 32-bit value used to represent the tokenized form of an ODType value.
Constants of this type

kODNullTypeToken
A null type token.
kODNullFocus
No focus. (This value is returned by focus iterators.)

You can call the session object's Tokenize method (page 622) to convert an ODType value into an ODTypeToken value.

Time
The following platform-independent type represents time.

ODTime
A 32-bit value representing a point in time as the number of seconds elapsed since midnight, January 1, 1970.

Arbitrary Data
The following types represent arbitrary data of various sizes.

ODByteArray
A structure representing foreign data larger than 4 bytes, or variable-length data in general.
            struct ODByteArray {
               ODULong       _maximum;
               ODULong       _length;
               ODUByte     * _buffer;
            };
(The SOMobjects(TM) IDL compiler may generate types equivalent to ODULong and ODUByte for the fields of this structure.)
Field descriptions

_maximum
The size (in bytes) of the memory block containing data. This field indicates the maximum size of data that can be stored there.
_length
The length (number of bytes) of the data currently in the memory block.
_buffer
A pointer to the memory block containing the data; this memory block is called the byte array's buffer.

In most cases, ODByteArray structures are used to pass raw data between OpenDoc and its clients. If a method expects a specific structure in a byte array's buffer, the method description explains what structure the buffer should contain.
ODUByte
An unsigned 8-bit value.
ODULong
An unsigned 32-bit value.
ODUShort
An unsigned 16-bit value.

General Programming Concepts
The following types and constants correspond to frequently used programming concepts.

ODBoolean
A Boolean value; the size of this type is platform-dependent.
Constants of this type

kODTrue
True.
kODFalse
False.
ODError
A 32-bit exception code. The section "Error Codes" on page 934 describes the constants defined for this type.
ODException
A structure describing an exception.
            struct ODException {
               ODError        error;
               char           message[256];
            };
Field descriptions

error
The error code identifying the exception.
message
A string, used only for debugging purposes, that contains additional information about the exception.
ODFlags
An unsigned 32-bit value used to represent a collection of flags.
ODPtr
A general-purpose pointer (that is, a pointer of type void*).
ODSize
An unsigned 32-bit integer value used to specify the size of a data type, a buffer, or a memory block.

The following constant is used throughout OpenDoc.

kODNULL
A 32-bit value representing null. This constant can be used for a null reference to an OpenDoc object of any class and for null values of most 32-bit data types.

The following constants must be used for null values of the indicated types: kODNullTypeToken (page 877) for the ODTypeToken type; kODNullFocus (page 877) for a null tokenized focus type; kODNULLKey (page 903) for the ODStorageUnitKey type; kODNULLID (page 899) for the types ODID, ODDocumentID, ODDraftID, and ODStorageUnitID; and kODNoEditor (page 929) for the ODEditor type.