580 lines
14 KiB
C
580 lines
14 KiB
C
/*
|
|
File: AEHelpers.h
|
|
|
|
Contains: AEPrint, AEBuild and AEStream for Carbon
|
|
|
|
Version: QuickTime 7.3
|
|
|
|
Copyright: (c) 2007 (c) 1999-2001 by Apple Computer, Inc., all rights reserved.
|
|
|
|
Bugs?: For bug reports, consult the following page on
|
|
the World Wide Web:
|
|
|
|
http://developer.apple.com/bugreporter/
|
|
|
|
*/
|
|
/*
|
|
* Originally from AEGIzmos by Jens Alfke, circa 1992.
|
|
*/
|
|
#ifndef __AEHELPERS__
|
|
#define __AEHELPERS__
|
|
|
|
#ifndef __APPLEEVENTS__
|
|
#include <AppleEvents.h>
|
|
#endif
|
|
|
|
#ifndef __AEDATAMODEL__
|
|
#include <AEDataModel.h>
|
|
#endif
|
|
|
|
#include <stdarg.h>
|
|
|
|
|
|
#if PRAGMA_ONCE
|
|
#pragma once
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#if PRAGMA_IMPORT
|
|
#pragma import on
|
|
#endif
|
|
|
|
#if PRAGMA_STRUCT_ALIGN
|
|
#pragma options align=mac68k
|
|
#elif PRAGMA_STRUCT_PACKPUSH
|
|
#pragma pack(push, 2)
|
|
#elif PRAGMA_STRUCT_PACK
|
|
#pragma pack(2)
|
|
#endif
|
|
|
|
/*
|
|
* AEBuild:
|
|
*
|
|
* AEBuild provides a very high level abstraction for building
|
|
* complete AppleEvents and complex ObjectSpeciers. Using AEBuild it
|
|
* is easy to produce a textual representation of an AEDesc. The
|
|
* format is similar to the stdio printf call, where meta data is
|
|
* extracted from a format string and used to build the final
|
|
* representation.
|
|
*
|
|
* The structure of the format string is described here:
|
|
*
|
|
* < describe it >
|
|
*/
|
|
/* Syntax Error Codes: */
|
|
typedef UInt32 AEBuildErrorCode;
|
|
enum {
|
|
aeBuildSyntaxNoErr = 0, /* (No error) */
|
|
aeBuildSyntaxBadToken = 1, /* Illegal character */
|
|
aeBuildSyntaxBadEOF = 2, /* Unexpected end of format string */
|
|
aeBuildSyntaxNoEOF = 3, /* Unexpected extra stuff past end */
|
|
aeBuildSyntaxBadNegative = 4, /* "-" not followed by digits */
|
|
aeBuildSyntaxMissingQuote = 5, /* Missing close "'" */
|
|
aeBuildSyntaxBadHex = 6, /* Non-digit in hex string */
|
|
aeBuildSyntaxOddHex = 7, /* Odd # of hex digits */
|
|
aeBuildSyntaxNoCloseHex = 8, /* Missing "." */
|
|
aeBuildSyntaxUncoercedHex = 9, /* Hex string must be coerced to a type */
|
|
aeBuildSyntaxNoCloseString = 10, /* Missing """ */
|
|
aeBuildSyntaxBadDesc = 11, /* Illegal descriptor */
|
|
aeBuildSyntaxBadData = 12, /* Bad data value inside (...) */
|
|
aeBuildSyntaxNoCloseParen = 13, /* Missing ")" after data value */
|
|
aeBuildSyntaxNoCloseBracket = 14, /* Expected "," or "]" */
|
|
aeBuildSyntaxNoCloseBrace = 15, /* Expected "," or "}" */
|
|
aeBuildSyntaxNoKey = 16, /* Missing keyword in record */
|
|
aeBuildSyntaxNoColon = 17, /* Missing ":" after keyword in record */
|
|
aeBuildSyntaxCoercedList = 18, /* Cannot coerce a list */
|
|
aeBuildSyntaxUncoercedDoubleAt = 19 /* "@@" substitution must be coerced */
|
|
};
|
|
|
|
/* A structure containing error state.*/
|
|
|
|
struct AEBuildError {
|
|
AEBuildErrorCode fError;
|
|
UInt32 fErrorPos;
|
|
};
|
|
typedef struct AEBuildError AEBuildError;
|
|
/*
|
|
Create an AEDesc from the format string. AEBuildError can be NULL, in which case
|
|
no explicit error information will be returned.
|
|
*/
|
|
/*
|
|
* AEBuildDesc()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEBuildDesc(
|
|
AEDesc * dst,
|
|
AEBuildError * error, /* can be NULL */
|
|
const char * src,
|
|
...);
|
|
|
|
|
|
/* varargs version of AEBuildDesc*/
|
|
/*
|
|
* vAEBuildDesc()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
vAEBuildDesc(
|
|
AEDesc * dst,
|
|
AEBuildError * error, /* can be NULL */
|
|
const char * src,
|
|
va_list args);
|
|
|
|
|
|
|
|
/* Append parameters to an existing AppleEvent*/
|
|
/*
|
|
* AEBuildParameters()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEBuildParameters(
|
|
AppleEvent * event,
|
|
AEBuildError * error, /* can be NULL */
|
|
const char * format,
|
|
...);
|
|
|
|
|
|
/* varargs version of AEBuildParameters*/
|
|
/*
|
|
* vAEBuildParameters()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
vAEBuildParameters(
|
|
AppleEvent * event,
|
|
AEBuildError * error, /* can be NULL */
|
|
const char * format,
|
|
va_list args);
|
|
|
|
|
|
/* Building an entire Apple event:*/
|
|
/*
|
|
* AEBuildAppleEvent()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEBuildAppleEvent(
|
|
AEEventClass theClass,
|
|
AEEventID theID,
|
|
DescType addressType,
|
|
const void * addressData,
|
|
long addressLength,
|
|
short returnID,
|
|
long transactionID,
|
|
AppleEvent * result,
|
|
AEBuildError * error, /* can be NULL */
|
|
const char * paramsFmt,
|
|
...);
|
|
|
|
|
|
/* varargs version of AEBuildAppleEvent*/
|
|
/*
|
|
* vAEBuildAppleEvent()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
vAEBuildAppleEvent(
|
|
AEEventClass theClass,
|
|
AEEventID theID,
|
|
DescType addressType,
|
|
const void * addressData,
|
|
long addressLength,
|
|
short returnID,
|
|
long transactionID,
|
|
AppleEvent * resultEvt,
|
|
AEBuildError * error, /* can be NULL */
|
|
const char * paramsFmt,
|
|
va_list args);
|
|
|
|
|
|
/*
|
|
* AEPrintDescToHandle
|
|
*
|
|
* AEPrintDescToHandle provides a way to turn an AEDesc into a textual
|
|
* representation. This is most useful for debugging calls to
|
|
* AEBuildDesc and friends. The Handle returned should be disposed by
|
|
* the caller. The size of the handle is the actual number of
|
|
* characters in the string.
|
|
*/
|
|
/*
|
|
* AEPrintDescToHandle()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEPrintDescToHandle(
|
|
const AEDesc * desc,
|
|
Handle * result);
|
|
|
|
|
|
/*
|
|
* AEStream:
|
|
*
|
|
* The AEStream interface allows you to build AppleEvents by appending
|
|
* to an opaque structure (an AEStreamRef) and then turning this
|
|
* structure into an AppleEvent. The basic idea is to open the
|
|
* stream, write data, and then close it - closing it produces an
|
|
* AEDesc, which may be partially complete, or may be a complete
|
|
* AppleEvent.
|
|
*/
|
|
typedef struct OpaqueAEStreamRef* AEStreamRef;
|
|
/*
|
|
Create and return an AEStreamRef
|
|
Returns NULL on memory allocation failure
|
|
*/
|
|
/*
|
|
* AEStreamOpen()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( AEStreamRef )
|
|
AEStreamOpen(void);
|
|
|
|
|
|
/*
|
|
Closes and disposes of an AEStreamRef, producing
|
|
results in the desc. You must dispose of the desc yourself.
|
|
If you just want to dispose of the AEStreamRef, you can pass NULL for desc.
|
|
*/
|
|
/*
|
|
* AEStreamClose()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamClose(
|
|
AEStreamRef ref,
|
|
AEDesc * desc);
|
|
|
|
|
|
/*
|
|
Prepares an AEStreamRef for appending data to a newly created desc.
|
|
You append data with AEStreamWriteData
|
|
*/
|
|
/*
|
|
* AEStreamOpenDesc()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamOpenDesc(
|
|
AEStreamRef ref,
|
|
DescType newType);
|
|
|
|
|
|
/* Append data to the previously opened desc.*/
|
|
/*
|
|
* AEStreamWriteData()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamWriteData(
|
|
AEStreamRef ref,
|
|
const void * data,
|
|
Size length);
|
|
|
|
|
|
/*
|
|
Finish a desc. After this, you can close the stream, or adding new
|
|
descs, if you're assembling a list.
|
|
*/
|
|
/*
|
|
* AEStreamCloseDesc()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamCloseDesc(AEStreamRef ref);
|
|
|
|
|
|
/* Write data as a desc to the stream*/
|
|
/*
|
|
* AEStreamWriteDesc()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamWriteDesc(
|
|
AEStreamRef ref,
|
|
DescType newType,
|
|
const void * data,
|
|
Size length);
|
|
|
|
|
|
/* Write an entire desc to the stream*/
|
|
/*
|
|
* AEStreamWriteAEDesc()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamWriteAEDesc(
|
|
AEStreamRef ref,
|
|
const AEDesc * desc);
|
|
|
|
|
|
/*
|
|
Begin a list. You can then append to the list by doing
|
|
AEStreamOpenDesc, or AEStreamWriteDesc.
|
|
*/
|
|
/*
|
|
* AEStreamOpenList()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamOpenList(AEStreamRef ref);
|
|
|
|
|
|
/* Finish a list.*/
|
|
/*
|
|
* AEStreamCloseList()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamCloseList(AEStreamRef ref);
|
|
|
|
|
|
/*
|
|
Begin a record. A record usually has type 'reco', however, this is
|
|
rather generic, and frequently a different type is used.
|
|
*/
|
|
/*
|
|
* AEStreamOpenRecord()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamOpenRecord(
|
|
AEStreamRef ref,
|
|
DescType newType);
|
|
|
|
|
|
/* Change the type of a record.*/
|
|
/*
|
|
* AEStreamSetRecordType()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamSetRecordType(
|
|
AEStreamRef ref,
|
|
DescType newType);
|
|
|
|
|
|
/* Finish a record*/
|
|
/*
|
|
* AEStreamCloseRecord()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamCloseRecord(AEStreamRef ref);
|
|
|
|
|
|
/*
|
|
Add a keyed descriptor to a record. This is analogous to AEPutParamDesc.
|
|
it can only be used when writing to a record.
|
|
*/
|
|
/*
|
|
* AEStreamWriteKeyDesc()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamWriteKeyDesc(
|
|
AEStreamRef ref,
|
|
AEKeyword key,
|
|
DescType newType,
|
|
const void * data,
|
|
Size length);
|
|
|
|
|
|
/*
|
|
OpenDesc for a keyed record entry. You can use AEStreamWriteData
|
|
after opening a keyed desc.
|
|
*/
|
|
/*
|
|
* AEStreamOpenKeyDesc()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamOpenKeyDesc(
|
|
AEStreamRef ref,
|
|
AEKeyword key,
|
|
DescType newType);
|
|
|
|
|
|
/* Write a key to the stream - you can follow this with an AEWriteDesc.*/
|
|
/*
|
|
* AEStreamWriteKey()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamWriteKey(
|
|
AEStreamRef ref,
|
|
AEKeyword key);
|
|
|
|
|
|
/*
|
|
Create a complete AppleEvent. This creates and returns a new stream.
|
|
Use this call to populate the meta fields in an AppleEvent record.
|
|
After this, you can add your records, lists and other parameters.
|
|
*/
|
|
/*
|
|
* AEStreamCreateEvent()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( AEStreamRef )
|
|
AEStreamCreateEvent(
|
|
AEEventClass clazz,
|
|
AEEventID id,
|
|
DescType targetType,
|
|
const void * targetData,
|
|
long targetLength,
|
|
short returnID,
|
|
long transactionID);
|
|
|
|
|
|
/*
|
|
This call lets you augment an existing AppleEvent using the stream
|
|
APIs. This would be useful, for example, in constructing the reply
|
|
record in an AppleEvent handler. Note that AEStreamOpenEvent will
|
|
consume the AppleEvent passed in - you can't access it again until the
|
|
stream is closed. When you're done building the event, AEStreamCloseStream
|
|
will reconstitute it.
|
|
*/
|
|
/*
|
|
* AEStreamOpenEvent()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( AEStreamRef )
|
|
AEStreamOpenEvent(AppleEvent * event);
|
|
|
|
|
|
/* Mark a keyword as being an optional parameter.*/
|
|
/*
|
|
* AEStreamOptionalParam()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.1 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
AEStreamOptionalParam(
|
|
AEStreamRef ref,
|
|
AEKeyword key);
|
|
|
|
|
|
|
|
#if PRAGMA_STRUCT_ALIGN
|
|
#pragma options align=reset
|
|
#elif PRAGMA_STRUCT_PACKPUSH
|
|
#pragma pack(pop)
|
|
#elif PRAGMA_STRUCT_PACK
|
|
#pragma pack()
|
|
#endif
|
|
|
|
#ifdef PRAGMA_IMPORT_OFF
|
|
#pragma import off
|
|
#elif PRAGMA_IMPORT
|
|
#pragma import reset
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __AEHELPERS__ */
|
|
|