1

common/quicktime_win32/AEHelpers.h

@@ -0,0 +1,579 @@
+/*
+     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__ */
+