MOA Developer's Guide
MOA Interfaces | MOA Methods


Director Xtra Development Kit: MOA API Reference

MOA Types and Miscellaneous API

This document contains the following sections:


MOA Types

Defined in: moatypes.h

The following standard types are defined by MOA for use in various interfaces, including both MOA standard interfaces and application specific interfaces.

General types


MoaChar,
PMoaChar,
ConstPMoaChar

MoaChar Signed character type
PMoaChar Pointer to null-terminated C string
ConstPMoaChar Pointer to constant character string


MoaBool

Boolean value type


MoaByte

Byte value type


MoaShort

Short integer type


MoaUshort

Unsigned short integer type


MoaLong

Long integer type


MoaUlong

Unsigned long integer type


MoaFixed

16.16 fixed-point number


MoaError

Standard error type used as return value to most methods


MoaFloat

32-bit IEEE floating point number


MoaDouble

Double floating point number. In Metrowerks, defined as a 64-bit type, regardless of "8-byte double" and "Gen 881"; 64-bit IEEE floating point number in other environments


PMoaVoid,
ConstPMoaVoid,
PPMoaVoid

PMoaVoid Pointer to a void type
ConstPMoaVoid Pointer to a void type constant
PPMoaVoid Pointer to pointer to a void type constant


MoaCharParam

Character parameter type; for types < 32 bits, this is the long-sized versions for argument lists


MoaBoolParam

Boolean parameter type


MoaWide

Double long integer, defined differently (but compatibly) for the two platforms currently supported. On the Macintosh, defined to match the wide integer type. In Windows defined to match the LARGE_INTEGER type

2D Graphics Types


MoaCoord

MoaCoord MoaLong

Moa graphic coordinate type


MoaPoint
typedef struct MoaPoint {
        MoaCoord y;
        MoaCoord x;
} MoaPoint;

Type representing a position in two-dimensional coordinate space. y represents the vertical position of the point, x represents the horizontal position.

MoaPoint Structure type
PMoaPoint Pointer type
ConstPMoaPoint Constant pointer type


MoaRect
typedef struct MoaRect {
        MoaCoord top;
        MoaCoord left;
        MoaCoord bottom;
        MoaCoord right;
} MoaRect;

Structure representing a rectangular area in two-dimensional coordinate space. top represents the upper bounding coordinate of the area, left represents the left side bounding coordinate, bottom represents the bottom bounds and right represents the right side coordinate.

MoaRect Structure type
PMoaRect Pointer type
ConstPMoaRect Constant pointer type

IMoaStream types


MoaStreamPosition

Type for specifying current position


MoaStreamCount

Type for specifying size

IMoaFile types


MoaSystemFileSpec

typedef MoaChar MoaSystemFileSpec[MOA_MAX_PATHNAME]


MoaFileEachProc
MoaError MoaFileEachProc(
        ConstPMoaSystemFileSpec pSpec,
        ConstPMoaChar pFileName,
        MoaBoolParam isDirectory, 
        MoaWide lastModDate,
        MoaUlong fileType,
        PMoaVoid refCon)
Enumeration function prototype for IMoaFile::EachFile() method.


MOA Constants

Defined in: moatypes.h

Boolean Constants

TRUE 1
FALSE 0

IMoaAppInfo constants

These constants are used for obtaining information about the Xtra's host application through the IMoaAppInfo callback interface. The desiredInfo parameter specifies the type of information being requested; it can be one of the following enumerated constants:

Constant Description
kMoaAppInfo_SerialNumber Application serial number as a string. Format of a serial number is unspecified, except that it is guaranteed to be less than 256 bytes long. An empty string may be returned.
kMoaAppInfo_RunMode RunMode of the app as a string. Defined modes are:
"Author" authoring application
"Projector" projector-only application
These values are not localized.
kMoaAppInfo_UserName the user name entered at registration.
kMoaAppInfo_OrganizationName the company/organization name entered at registration.
kMoaAppInfo_AppFileSpec a MoaSystemFileSpec to the application/projector executable. This is a MoaSystemFileSpec, not a character string, thus on the Macintosh you will receive an FSSpec.
kMoaAppInfo_ProductName The name of the product, minus version information. This is not localized. Currently defined are "Director", "SoundEdit", "FreeHand"
kMoaAppInfo_ProductVersion Version of the product, generally a character string representing a number, though it may include letters as well, e.g., "5.0","5.0a", "5.5"

Note that not all apps will support all these; you must be prepared for an app to return kMoaErr_NoSuchKey for any or all of these. additional values may be added in the future.

The parameters pInfoBuffer and infoBufferLen provide the application with a buffer to write the corresponding information to.

IMoaDict constants

Entry Constant

MoaDictTypeID 32 bit numbers representing the type of an entry.

The first 2^16 MoaDictTypeID values are reserved by MOA. (The types IDs enumerated so are listed above.) Type ID values above the reserved range are dynamically assigned at runtime and map to an object exporting the IMoaDict interface. These can be looked up either using the well known types dictionary or by enumerating MOA interfaces.

Data Type Constants

kMoaDictType_Bogus Illegal entry type.
kMoaDictType_Long MoaLong
kMoaDictType_Float 32 bit IEEE single-precision floating-point number
kMoaDictType_Wide MoaWide
kMoaDictType_Bool MoaBool
kMoaDictType_MoaID MoaID
kMoaDictType_Bytes Arbitrary bytes
kMoaDictType_CString Null-terminated C String
kMoaDictType_Dict PIMoaDict (see note)
kMoaDictType_PIMoaUnknown Arbitrary MOA interface. When storing interfaces in a dictionary, calling Put() on the containing IMoaDict calls AddRef() on the interface being stored; calling Remove() on the IMoaDict calls Release() on the interface.


Runtime Key Identifier Constant

MOADICT_RUNTIME_KEY_PREFIX "_rt_"

By convention, all keys beginning with these characters will never be written to persistent storage; they are runtime-only keys.

IMoaStream constants

These constants are used with methods of the IMoaStream interface.

Access Mode Constants

kMoaStreamOpenAccess_ReadOnly Open stream for reading
kMoaStreamOpenAccess_ReadWrite Open stream for reading and writing
kMoaStreamOpenAccess_WriteOnly Open stream for writing


ReadAhead Limit Constants

kMoaStreamReadAheadLimit Bytes available to ReadAhead() (value may be implementation dependent)


Set Position Constants

These constants are passed to Open() to specify use of SetPosition(). This API enables the stream to optimize for particular seeking needs.

kMoaStreamSetPositionType_None Never calls SetPosition()
kMoaStreamSetPositionType_Expensive Rarely calls SetPosition(); don't optimize
kMoaStreamSetPositionType_Cheap Often calls SetPosition(); optimize seek

IMoaFile constants

These constants are used with methods of the IMoaFile interface.


File access constants
kMoaFileAccessPerm_Read
kMoaFileAccessPerm_Write


File name size constants
MOA_MAX_PATHNAME 		(1024) // This value was increased for D11
MOA_MAX_FILENAME 		(1024)


MOA Globals

gXtraFileRef

Defined in: moatxtra.h

MOA reference to the Xtra object file. This value is a MoaFileRef, a MOA-specific type used only as an argument to the IMoaCallback interface methods MoaBeginUsingResources() and MoaEndUsingResources(). This value enables MOA to identify the resource file associated with an Xtra.


MOA Functions

MOAID comparison function

Defined in: moaxtra.h


MoaEqualID()
MoaLong MoaEqualID(ConstPMoaID a,
        ConstPMoaID b)

a, b MoaIDs to compare

Returns Boolean result of comparison

Use this function to test the values in two MoaIDs, for example, to find an entry for a particular interface in the cache.


MOA Macros

Wide Integer Handlers

Defined in: moatypes.h

The following macros are defined in MOA for use in evaluating and converting values of type s.


LONG_TO_WIDE()

LONG_TO_WIDE(L, W)

L Long integer to convert
W Wide integer to contain the return value

Converts the MoaLong integer L to a MoaWide integer and puts the result in W.


WIDE_ADD_WIDE()

WIDE_ADD_WIDE(x, y)

x MoaWide to add and return result
y MoaWide to add


WIDE_EQ_ZERO()

WIDE_EQ_ZERO(x)

W Wide integer to test


Tests the MoaWide value x to see if it represents zero. Returns MoaBool result of test


WIDE_FITS()

WIDE_FITS(W)

W Wide integer to test


Returns: MoaBool result of test

Tests whether the MoaWide integer W can be converted to a MoaLong.


WIDE_GT_ZERO()

WIDE_GT_ZERO(x)

W
Wide integer to test

Returns MoaBool result of test

Tests the MoaWide value x to see if it represents a positive number.


WIDE_LT_ZERO()
WIDE_LT_ZERO(x)
X Wide integer to test


Returns: MoaBool result of test

Tests the MoaWide value x to see if it represents a negative number.


WIDE_NEGATE()

WIDE_NEGATE(x)

x

MoaWide to negate and return result

Negates the MoaWide value x.


WIDE_TO_LONG()

WIDE_TO_LONG(W, L)

W Wide integer to convert
L Long integer to contain the return value


Converts the MoaWide integer W to a MoaLong integer and puts the result in L.

2D Graphics Macros


MoaToMacPoint()

MoaToMacPoint(moa,mac)

moa MOA point to convert
mac Mac point to receive the result


MacToMoaPoint()

MacToMoaPoint(mac, moa)

mac Mac point to convert
moa MOA point to receive the result


MoaToMacRect()

MoaToMacRect(a,b)

a MOA rect to convert
b Mac rect to receive the result


MacToMoaRect()

MacToMoaRect(a, b)

a Mac rect to convert
b MOA rect to receive the result


MoaToWinPoint()

MoaToWinPoint(moa,win)

moa MOA point to convert
win Windows point to receive the result


WinToMoaPoint()

WinToMoaPoint(win, moa)

win Windows point to convert
moa MOA point to receive the result


MoaToWinRect()

MoaToWinRect(a,b)

a Moa rect to convert
b Windows rect to receive result


WinToMoaRect()

WinToMoaRect(a, b)

a Windows rect to convert
b MOA rect to receive result

Error Code Generator


MAKE_MOAERR()

MAKE_MOAERR(code)

code MoaLong to convert to standard MOA error code


Converts code to a value that conforms with standard MOA error code conventions.


MOA Errors

Header files: moatypes.h


The following constants provide standard return values for MOA methods that return MoaError. Certain MOA and application-specific interfaces define additional error codes; see interface descriptions for details.

Success code

This error code is the standard return value for successful MOA method calls.

kMoaErr_NoErr Successful call

Calling errors

The following codes represent standard errors that may be returned from a number of MOA methods, in interfaces implemented by the application and in the interfaces you implement. Your code may encounter these errors when calling MOA methods; you can write your code to handle these errors in the appropriate ways. Your code should return these codes when it encounters corresponding error conditions.

kMoaErr_BadParam Bogus argument to a method
kMoaErr_OutOfMem Core "memory full" error
kMoaErr_XtraInUse Xtra has objects in use
kMoaErr_BadInterface Interface not recognized
kMoaErr_BadClass Class not recognized
kMoaErr_FileNotFound File not found or not opened
kMoaErr_XtraNotFound Xtra not found in file
kMoaErr_FuncNotFound Function missing from Xtra
kMoaErr_ClassInfoNotFound Class information missing from Xtra
kMoaErr_ConnectionNotOpen Xtra not properly opened (internal error)

Initialization errors

The following codes enable Xtras to report when they can't run on a given configuration. Xtras should return these codes to indicate failure in their IMoaRegister or IMoaInitFromDict interface.

kMoaErr_NotEnoughCPU Xtra requires newer CPU
kMoaErr_NotEnoughFPU Xtra requires an FPU
kMoaErr_NotEnoughHardware Extra hardware required
kMoaErr_NotEnoughSSW System software incompatible
kMoaErr_NotEnoughExtraSSW Missing extensions (e.g., QuickTime)
kMoaErr_NotEnoughDiskSpace Need more free space on disk
kMoaErr_NoUnusedFreed MoaFreeUnused couldn't free mem
kMoaErr_RequiredCallbackMissing A required interface wasn't supplied

IMoaDict errors

Errors returned by methods of IMoaDict.

kMoaDictErr_NotFound Lookup of a nonexistent key.
kMoaDictErr_WrongType Key exists but holds different type than requested.
kMoaDictErr_CantWrite Attempt to put or remove value where not allowed (e.g. structure dicts).
kMoaDictErr_BufferTooSmall Value won't fit into the buffer you passed.

IMoaFile errors

Errors returned by methods of IMoaFile.

kMoaFileErr_IoError
kMoaFileErr_BufferTooSmall
kMoaFileErr_DuplicateSpec
kMoaFileErr_DiskFull
kMoaFileErr_FileBusy
kMoaFileErr_BadFileSpec

IMoaStream errors

Errors returned by methods of IMoaStream.

kMoaStreamErr_StreamNotOpen Returned when calling any method before Open()
kMoaStreamErr_StreamAlreadyOpen Returned when re-calling Open()
kMoaStreamErr_BadParameter Bad parameter
kMoaStreamErr_IoError Read/write/positioning error
kMoaStreamErr_ReadPastEnd Attempted to read past end
kMoaStreamErr_BadAccessMode Not an allowable read/write parameter
kMoaStreamErr_BadSetPositionMode Not an allowable seek parameter
kMoaStreamErr_ReadAheadToo Requested too many bytes from ReadAhead()
kMoaStreamErr_WrotePastEnd Attempted to write too much: disk full, etc.



Copyright © 1995-2007 Adobe Macromedia Software LLC, Inc.