Inside Macintosh: Interapplication Communication /

Chapter 6 - Resolving and Creating Object Specifier Records

Summary of Resolving and Creating Object Specifier Records

Pascal Summary

Constants

CONST 
   gestaltAppleEventsAttr     = 'evnt';   {selector for Apple events}
   gestaltAppleEventsPresent  = 0;        {if this bit is set, Apple }
                                          { Event Manager is available}

   {logical operators for descriptor records with keyword } 
   { keyAELogicalOperator}
   kAEAND                  =  'AND ';     
   kAEOR                   =  'OR  ';
   kAENOT                  =  'NOT ';

   {absolute ordinals used as key data in an object specifier } 
   { record with key form formAbsolutePosition}
   kAEFirst                =  'firs';
   kAELast                 =  'last';
   kAEMiddle               =  'midd';
   kAEAny                  =  'any ';
   kAEAll                  =  'all ';

   {relative ordinals used as key data in an object specifier record }
   { with key form formRelativePosition}
   kAENext                 =  'next';
   kAEPrevious             =  'prev';
   
   {keywords for object specifier records} 
   keyAEDesiredClass       =  'want'; {object class ID}
   keyAEContainer          =  'from'; {description of container}
   keyAEKeyForm            =  'form'; {key form}
   keyAEKeyData            =  'seld'; {key data for specified key form}

   {keywords for range descriptor records}
   keyAERangeStart         =  'star';     {beginning of range}
   keyAERangeStop          =  'stop';     {end of range}
   
   {values for the keyAEKeyForm field of an object specifier record} 
   formAbsolutePosition    =  'indx';     {for example, 1 = first }
                                          { element in container, -2 = }
                                          { second from end of container}
   formRelativePosition    =  'rele';     {key data specifies element }
                                          { before or after container}
   formTest                =  'test';     {key data specifies a test}
   formRange               =  'rang';     {key data specifies a range}
   formPropertyID          =  'prop';     {key data is property ID}
   formName                =  'name';     {key data is element's name}

   {descriptor types used to identify Apple event objects}
   typeObjectSpecifier     =  'obj ';     {object specifier record, often }
                                          { used as keyAEContainer}
   typeObjectBeingExamined =  'exmn';     {used as keyAEContainer}
   typeCurrentContainer    =  'ccnt';     {used as keyAEContainer}
   typeToken               =  'toke';     {substituted for 'ccnt' }
                                          { before accessor called}
   typeAbsoluteOrdinal     =  'abso';     {formAbsolutePosition}
   typeRangeDescriptor     =  'rang';     {formRange}
   typeLogicalDescriptor   =  'logi';     {formTest}
   typeCompDescriptor      =  'cmpd';     {formTest}

   {various relevant keywords}
   keyAECompOperator       =  'relo';     {operator for comparison: }
                                          { '=', '<=', etc.}
   keyAELogicalTerms       =  'term';     {an AEList of terms to be }
                                          { related by 'logc' below}
   keyAELogicalOperator    =  'logc';     {kAEAND, kAEOR, or kAENOT}
   keyAEObject1            =  'obj1';     {first of two objects being }
                                          { compared; must be object }
                                          { specifier record}
   keyAEObject2            =  'obj2';     {the other object; may be }
                                          { simple descriptor record }
                                          { or object specifier record}

   {special handler selectors used with AESetObjectCallbacks}
   keyDisposeTokenProc     =  'xtok';
   keyAECompareProc        =  'cmpr';
   keyAECountProc          =  'cont';
   keyAEMarkTokenProc      =  'mkid';
   keyAEMarkProc           =  'mark';
   keyAEAdjustMarksProc    =  'adjm';
   keyAEGetErrDescProc     =  'indc';

   {additive values for callbackFlags parameter to AEResolve}
   kAEIDoMinimum           =  $0000;   {server does not support whose }
                                       { descriptor records or marking}
   kAEIDoWhose             =  $0001;   {server supports whose }
                                       { descriptor records}
   kAEIDoMarking           =  $0004;   {server supports marking}

   {constants for whose descriptor records}
   typeWhoseDescriptor     =  'whos';  {whose descriptor record}
   formWhose               =  'whos';  {key form for key data of descriptor }
                                       { type typeWhoseDescriptor}
   typeWhoseRange          =  'wrng';  {whose range descriptor record}
   keyAEWhoseRangeStart    =  'wstr';  {beginning of range}
   keyAEWhoseRangeStop     =  'wstp';  {end of range}
   keyAEIndex              =  'kidx';  {index for whose descriptor record}
   keyAETest               =  'ktst';  {test for whose descriptor record}

Data Types

TYPE
   ccntTokenRecord =                      {used for rewriting tokens in }
   RECORD                                 { place of 'ccnt' descriptor }
      tokenClass:    DescType;            { records; only of interest to }
      token:         AEDesc;              { those who, when they get ranges }
   END;                                   { as key data in their object }
                                          { accessor functions, resolve }
   ccntTokenRecPtr = ^ccntTokenRecord;    { the object specifier records }
   ccntTokenRecHandle = ^ccntTokenRecPtr; { for the end points manually}

   DescPtr = ^AEDesc;
   DescHandle = ^DescPtr;

   AccessorProcPtr = ProcPtr;

Routines for Resolving and Creating Object Specifier Records

Initializing the Object Support Library

FUNCTION AEObjectInit : OSErr;

Setting Object Accessor Functions and Object Callback Functions

FUNCTION AEInstallObjectAccessor
(desiredClass: DescType; 
containerType: DescType; 
theAccessor: AccessorProcPtr; 
accessorRefcon: LongInt; 
isSysHandler: Boolean): OSErr;
FUNCTION AESetObjectCallbacks
(myCompareProc, myCountProc, 
myDisposeTokenProc,										
myGetMarkTokenProc, myMarkProc,
myAdjustMarksProc, myGetErrDescProc: 
ProcPtr): OSErr;

Getting, Calling, and Removing Object Accessor Functions

FUNCTION AEGetObjectAccessor
(desiredClass: DescType; 
containerType: DescType;
VAR theAccessor: AccessorProcPtr;
VAR accessorRefcon: LongInt; 
isSysHandler: Boolean): OSErr;
FUNCTION AECallObjectAccessor
(desiredClass: DescType; 
containerToken: AEDesc;
containerClass: DescType; 
keyForm: DescType; 
keyData: AEDesc; 
VAR theToken: AEDesc): OSErr;
FUNCTION AERemoveObjectAccessor
(desiredClass: DescType; 
containerType: DescType; 
theAccessor: AccessorProcPtr; 
isSysHandler: Boolean): OSErr;

Resolving Object Specifier Records

FUNCTION AEResolve (objectSpecifier: AEDesc; 
callbackFlags: Integer;
VAR theToken: AEDesc): OSErr;

Deallocating Memory for Tokens

FUNCTION AEDisposeToken (VAR theToken: AEDesc): OSErr;

Creating Object Specifier Records

FUNCTION CreateOffsetDescriptor
(theOffset: LongInt; 
VAR theDescriptor: AEDesc): 
OSErr;
FUNCTION CreateCompDescriptor
(comparisonOperator: DescType;
VAR operand1: AEDesc; 
VAR operand2: AEDesc; 
disposeInputs: Boolean; 
VAR theDescriptor: AEDesc): OSErr;
FUNCTION CreateLogicalDescriptor
(VAR theLogicalTerms: AEDescList; 
theLogicOperator: DescType; 
disposeInputs: Boolean; 
VAR theDescriptor: AEDesc): OSErr;
FUNCTION CreateRangeDescriptor
(VAR rangeStart: AEDesc; 
VAR rangeStop: AEDesc; 
disposeInputs: Boolean; 
VAR theDescriptor: AEDesc): OSErr;
FUNCTION CreateObjSpecifier(desiredClass: DescType;
VAR theContainer: AEDesc; 
keyForm: DescType; 
VAR keyData: AEDesc; 
disposeInputs: Boolean; 
VAR objSpecifier: AEDesc): OSErr;

Application-Defined Routines

Object Accessor Functions

FUNCTION MyObjectAccessor (desiredClass: DescType; 
containerToken: AEDesc; 
containerClass: DescType; 
keyForm: DescType; keyData: AEDesc; 
VAR theToken: AEDesc; 
theRefcon: LongInt): OSErr;

Object Callback Functions

FUNCTION MyCountObjects(desiredClass: DescType; 
containerClass: DescType; 
theContainer: AEDesc; 
VAR result: LongInt): OSErr;
FUNCTION MyCompareObjects(comparisonOperator: DescType; 
theobject: AEDesc; 
objectOrDescToCompare: AEDesc; 
VAR result: Boolean): OSErr;
FUNCTION MyDisposeToken (VAR unneededToken: AEDesc): OSErr;
FUNCTION MyGetErrorDesc (VAR errDescPtr: DescPtr): OSErr;
FUNCTION MyGetMarkToken (containerToken: AEDesc; 
containerClass: DescType; 
VAR result: AEDesc): OSErr;
FUNCTION MyMark (theToken: AEDesc; markToken: AEDesc;
markCount: LongInt): OSErr;
FUNCTION MyAdjustMarks (newStart, newStop: LongInt; 
markToken: AEDesc): OSErr;

C Summary

Constants

enum {
      #define gestaltAppleEventsAttr     'evnt' /*selector for Apple events*/
      gestaltAppleEventsPresent        = 0   /*if this bit is set, then */
                                             /* Apple Event Manager is */
};                                           /* available*/

/*logical operators for descriptor records with keyword */ 
/* keyAELogicalOperator*/
#define kAEAND                      'AND '      
#define kAEOR                       'OR  '
#define kAENOT                      'NOT '

/*absolute ordinals used as key data in an object specifier */ 
/* record with key form formAbsolutePosition*/
#define kAEFirst                    'firs'
#define kAELast                     'last'
#define kAEMiddle                   'midd'
#define kAEAny                      'any '
#define kAEAll                      'all '

/*relative ordinals used as key data in an object specifier record */
/* with key form formRelativePosition*/
#define kAENext                     'next'
#define kAEPrevious                 'prev'

/*keywords for object specifier records*/    
#define keyAEDesiredClass           'want'   /*object class ID*/
#define keyAEContainer              'from'   /*description of container*/
#define keyAEKeyForm                'form'   /*key form*/
#define keyAEKeyData                'seld'   /*key data for specified key */
                                             /* form*/

/*keywords for range descriptor records*/
#define keyAERangeStart             'star'   /*beginning of range*/
#define keyAERangeStop              'stop'   /*end of range*/
   
/*values for the keyAEKeyForm field of an object specifier record*/ 
#define formAbsolutePosition        'indx'   /*for example, 1 = first */
                                             /* element in container, -2 = */
                                             /* second from end of */
                                             /* container*/
#define formRelativePosition        'rele'   /*key data specifies element */
                                             /* before or after container*/
#define formTest                    'test'   /*key data specifies a test*/
#define formRange                   'rang'   /*key data specifies a range*/
#define formPropertyID              'prop'   /*key data is property ID*/
#define formName                    'name'   /*key data is element's name*/

/* descriptor types used to identify Apple event objects*/
#define typeObjectSpecifier         'obj '   /*object specifier record, */
                                             /* often used as */
                                             /* keyAEContainer*/
#define typeObjectBeingExamined     'exmn'   /*used as keyAEContainer*/
#define typeCurrentContainer        'ccnt'   /*used as keyAEContainer*/
#define typeToken                   'toke'   /*substituted for 'ccnt' */
                                             /* before accessor called*/
#define typeAbsoluteOrdinal         'abso'   /*formAbsolutePosition*/
#define typeRangeDescriptor         'rang'   /*formRange*/
#define typeLogicalDescriptor       'logi'   /*formTest*/
#define typeCompDescriptor          'cmpd'   /*formTest*/
/*various relevant keywords*/
#define keyAECompOperator           'relo'   /*operator for comparison: */
                                             /* '=', '<=', etc.*/
#define keyAELogicalTerms           'term'   /*an AEList of terms to be */
                                             /* related by 'logc' below*/
#define keyAELogicalOperator        'logc'   /*kAEAND, kAEOR, or kAENOT*/
#define keyAEObject1                'obj1'   /*first of two objects being */
                                             /* compared; must be object */
                                             /* specifier record*/
#define keyAEObject2                'obj2'   /*the other object; may be */
                                             /* simple descriptor record */
                                             /* or object specifier record*/
/*special handler selectors used with AESetObjectCallbacks*/
#define keyDisposeTokenProc         'xtok'
#define keyAECompareProc            'cmpr'
#define keyAECountProc              'cont'
#define keyAEMarkTokenProc          'mkid'
#define keyAEMarkProc               'mark'
#define keyAEAdjustMarksProc        'adjm'
#define keyAEGetErrDescProc         'indc'

/*additive values for callbackFlags parameter to AEResolve*/
#define kAEIDoMinimum               0x0000   /*server does not support */
                                             /* whose descriptor records */
                                             /* or marking*/
#define kAEIDoWhose                 0x0001   /*server supports whose */
                                             /* descriptor records*/
#define kAEIDoMarking               0x0004   /*server supports marking*/

/*constants for whose descriptor records*/
#define typeWhoseDescriptor         'whos'   /*whose descriptor record*/
#define formWhose                   'whos'   /*key form for key data of */
                                             /* descriptor type */
                                             /* typeWhoseDescriptor*/
#define typeWhoseRange              'wrng'   /*whose range descriptor */
                                             /* record*/
#define keyAEWhoseRangeStart        'wstr'   /*beginning of range*/
#define keyAEWhoseRangeStop         'wstp'   /*end of range*/
#define keyAEIndex                  'kidx'   /*index for whose descriptor */
                                             /* record*/
#define keyAETest                   'ktst'   /*test for whose descriptor */
                                             /* record*/

Data Types

struct ccntTokenRecord {                     /*used for rewriting tokens */
   DescType tokenClass;                      /* in place of 'ccnt' */
   AEDesc token;                             /* descriptor records; only */
};                                           /* of interest to those who, */
                                             /* when they get ranges as */
typedef struct ccntTokenRecord ccntTokenRecord, /* key data in their object */
*ccntTokenRecPtr, **ccntTokenRecHandle;      /* accessor functions, */ 
                                             /* resolve them manually*/

typedef AEDesc *DescPtr, **DescHandle;

/*typedefs providing type checking for procedure pointers*/
typedef pascal OSErr (*accessorProcPtr) (DescType desiredClass,
                                          const AEDesc *container, 
                                          DescType containerClass, 
                                          DescType form,
                                          const AEDesc *selectionData, 
                                          AEDesc *value, long LongInt);
typedef pascal OSErr (*compareProcPtr)(DescType oper, const AEDesc *obj1,
                                       const AEDesc *obj2,
                                       Boolean *result);
typedef pascal OSErr (*countProcPtr)(DescType desiredClass, 
                                       DescType containerClass,
                                       const AEDesc *container, 
                                       long *result);
typedef pascal OSErr (*disposeTokenProcPtr)(AEDesc *unneededToken);
typedef pascal OSErr (*getMarkTokenProcPtr)(const AEDesc *ContainerToken, 
                                             DescType containerClass,
                                             AEDesc *result);

typedef pascal OSErr (*getErrDescProcPtr)(DescPtr *appDescPtr);

Routines for Resolving and Creating Object Specifier Records

Initializing the Object Support Library

pascal OSErr AEObjectInit();

Setting Object Accessor Functions and Object Callback Functions

pascal OSErr AEInstallObjectAccessor
(DescType desiredClass, DescType containerType,
accessorProcPtr theAccessor,
long accessorRefcon, Boolean isSysHandler);
pascal OSErr AESetObjectCallbacks
(compareProcPtr myCompareProc, 
countProcPtr myCountProc, 
disposeTokenProcPtr myDisposeTokenProc, 
getMarkTokenProcPtr myGetMarkTokenProc, markProcPtr myMarkProc, 
adjustMarksProcPtr myAdjustMarksProc, getErrDescProcPtr myGetErrDescProc);

Getting, Calling, and Removing Object Accessor Functions

pascal OSErr AEGetObjectAccessor
(DescType desiredClass, DescType containerType,
accessorProcPtr *theAccessor,
long *accessorRefcon, Boolean isSysHandler);
pascal OSErr AECallObjectAccessor
(DescType desiredClass, 
const AEDesc *containerToken, 
DescType containerClass, DescType keyForm, 
const AEDesc *keyData, AEDesc *theToken);
pascal OSErr AERemoveObjectAccessor
(DescType desiredClass, DescType containerType,
accessorProcPtr theAccessor, 
Boolean isSysHandler);

Resolving Object Specifier Records

pascal OSErr AEResolve(const AEDesc *objectSpecifier, 
short callbackFlags, AEDesc *theToken);

Deallocating Memory for Tokens

pascal OSErr AEDisposeToken(AEDesc *theToken);

Creating Object Specifier Records

pascal OSErr CreateOffsetDescriptor
(long theOffset, AEDesc *theDescriptor);
pascal OSErr CreateCompDescriptor
(DescType comparisonOperator, AEDesc* operand1,
AEDesc* operand2, Boolean											 disposeInputs, 
AEDesc* theDescriptor);
pascal OSErr CreateLogicalDescriptor
(AEDescList *theLogicalTerms, 
DescType theLogicOperator, 
Boolean disposeInputs, AEDesc *theDescriptor);
pascal OSErr CreateRangeDescriptor
(AEDesc *rangeStart, AEDesc *rangeStop,
Boolean disposeInputs, AEDesc *theDescriptor);
pascal OSErr CreateObjSpecifier
(DescType desiredClass, AEDesc *theContainer,
DescType										 keyForm, AEDesc *keyData, 
Boolean disposeInputs, AEDesc *objSpecifier);

Application-Defined Routines

Object Accessor Functions

pascal OSErr MyObjectAccessor
(DescType desiredClass, 
const AEDesc *containerToken, 
DescType containerClass, 
DescType keyForm, const AEDesc *keyData, 
AEDesc *theToken, long *theRefcon);

Object Callback Functions

pascal OSErr MyCountObjects(DescType desiredClass, DescType containerClass, 
const AEDesc *theContainer, long *result);
pascal OSErr MyCompareObjects
(DescType comparisonOperator, 
const AEDesc *theObject, 
const AEDesc *objectOrDescToCompare, 
Boolean *result);
pascal OSErr MyDisposeToken(AEDesc *unneededToken);
pascal OSErr MyGetErrorDesc(DescPtr *errDescPtr);
pascal OSErr MyGetMarkToken(const AEDesc *containerToken, 
DescType containerClass, AEDesc *result);
pascal OSErr MyMark(const AEDesc *theToken, 
const AEDesc *markToken, long markCount);
pascal OSErr MyAdjustMarks(long newStart, long newStop, 
const AEDesc *markToken);

Assembly-Language Summary

Trap Macros

Trap Macros Requiring Routine Selectors

_Pack8

Selector	Routine
$023A	AEDisposeToken
$0536	AEResolve
$0738	AERemoveObjectAccessor
$0937	AEInstallObjectAccessor
$0939	AEGetObjectAccessor
$0C3B	AECallObjectAccessor
$0E35	AESetObjectCallbacks

Result Codes

noErr	0	No error
paramErr	-50	Parameter error (for example, value of handler pointer is NIL or odd)
eLenErr	-92	Buffer too big to send
memFullErr	-108	Not enough room in heap zone
userCanceledErr	-128	User canceled an operation
procNotFound	-600	No eligible process with specified process serial number
bufferIsSmall	-607	Buffer is too small
noOutstandingHLE	-608	No outstanding high-level event
connectionInvalid	-609	Nonexistent signature or session ID
noUserInteractionAllowed	-610	Background application sends event requiring authentication
noPortErr	-903	Client hasn't set 'SIZE' resource to indicate awareness of high-level events
destPortErr	-906	Server hasn't set 'SIZE' resource to indicate awareness of high-level events, or else is not present
sessClosedErr	-917	The kAEDontReconnect flag in the sendMode parameter was set, and the server quit and then restarted
errAECoercionFail	-1700	Data could not be coerced to the requested descriptor type
errAEDescNotFound	-1701	Descriptor record was not found
errAECorruptData	-1702	Data in an Apple event could not be read
errAEWrongDataType	-1703	Wrong descriptor type
errAENotAEDesc	-1704	Not a valid descriptor record
errAEBadListItem	-1705	Operation involving a list item failed
errAENewerVersion	-1706	Need a newer version of the Apple Event Manager
errAENotAppleEvent	-1707	Event is not an Apple event
errAEEventNotHandled	-1708	Event wasn't handled by an Apple event handler
errAEReplyNotValid	-1709	AEResetTimer was passed an invalid reply
errAEUnknownSendMode	-1710	Invalid sending mode was passed
errAEWaitCanceled	-1711	User canceled out of wait loop for reply or receipt
errAETimeout	-1712	Apple event timed out
errAENoUserInteraction	-1713	No user interaction allowed
errAENotASpecialFunction	-1714	The keyword is not valid for a special function
errAEParamMissed	-1715	Handler cannot understand a parameter the client considers required
errAEUnknownAddressType	-1716	Unknown Apple event address type
errAEHandlerNotFound	-1717	No handler found for an Apple event or a coercion, or no object callback function found
errAEReplyNotArrived	-1718	Reply has not yet arrived
errAEIllegalIndex	-1719	Not a valid list index
errAEImpossibleRange	-1720	The range is not valid because it is impossible for a range to include the first and last objects that were specified; an example is a range in which the offset of the first object is greater than the offset of the last object
errAEWrongNumberArgs	-1721	The number of operands provided for the kAENOT logical operator is not 1
errAEAccessorNotFound	-1723	There is no object accessor function for the specified object class and token descriptor type
errAENoSuchLogical	-1725	The logical operator in a logical descriptor record is not kAEAND, kAEOR, or kAENOT
errAEBadTestKey	-1726	The descriptor record in a test key is neither a comparison descriptor record nor a logical descriptor record
errAENotAnObjectSpec	-1727	The objSpecifier parameter of AEResolve is not an object specifier record
errAENoSuchObject	-1728	A run-time resolution error, for example: object specifier record asked for the third element, but there are only 2.
errAENegativeCount	-1729	Object-counting function returned negative value
errAEEmptyListContainer	-1730	The container for an Apple event object is specified by an empty list
errAEUnknownObjectType	-1731	Descriptor type of token returned by AEResolve is not known to server application
errAERecordingIsAlreadyOn	-1732	Attempt to turn recording on when it is already on