Retired Document
Important: This sample code may not represent best practices for current development. The project may use deprecated symbols and illustrate technologies and techniques that are no longer recommended.
Relevant replacement documents include:
MoreAppleEvents/MoreAppleEvents.h
/* |
File: MoreAppleEvents.h |
Contains: |
Written by: Pete Gontier |
Copyright: Copyright (c) 1998 Apple Computer, Inc., All Rights Reserved. |
You may incorporate this Apple sample source code into your program(s) without |
restriction. This Apple sample source code has been provided "AS IS" and the |
responsibility for its operation is yours. You are not permitted to redistribute |
this Apple sample source code as "Apple sample source code" after having made |
changes. If you're going to re-distribute the source, we require that you make |
it clear in the source that the code was descended from Apple sample source |
code, but that you've made changes. |
Change History (most recent first): |
<9> 27/3/00 Quinn Remove MoreAEDeleteItemFromRecord. It's functionality is |
covered by AEDeleteKeyDesc. |
<8> 20/3/00 Quinn Added routines to deal with "missing value". Added |
MoreAECopyDescriptorDataToHandle. Fixed some copy and paste |
errors in the comments. |
<7> 3/9/00 GW Intergrating AppleEvent Helper code |
<6> 6/3/00 Quinn Added a bunch of trivial wrapper routines. George may come |
along and change all these soon, but I needed them for MoreOSL. |
<5> 1/3/00 Quinn Change the signature for AEGetDescData to match the version we |
actually shipped. |
<4> 2/15/99 PCG add AEGetDescDataSize for non-Carbon clients |
<3> 1/29/99 PCG add AEGetDescData |
<2> 11/11/98 PCG fix headers |
<1> 11/10/98 PCG first big re-org at behest of Quinn |
Old Change History (most recent first): |
<4> 10/11/98 Quinn Convert "MorePrefix.h" to "MoreSetup.h". |
<3> 9/9/98 PCG re-work import and export pragmas |
<2> 7/24/98 PCG coddle linker (C++, CFM-68K) |
<1> 6/16/98 PCG initial checkin |
*/ |
#pragma once |
//******************************************************************************** |
// A private conditionals file to setup the build environment for this project. |
#include "MoreSetup.h" |
//******************************************************************************** |
// System includes |
#include <AERegistry.h> |
#include <AEObjects.h> |
#include <AEPackObject.h> |
#include <EPPC.h> |
#include <Gestalt.h> |
#include <Processes.h> |
//******************************************************************************** |
#define kFlagNotSet -1 |
//******************************************************************************** |
#ifdef __cplusplus |
extern "C" { |
#endif |
/******************************************************************************** |
Create and return an AEDesc for the process target with the specified PSN. |
If no PSN is supplied the use the current process |
pAEEventClass input: The class of the event to be created. |
pAEEventID input: The ID of the event to be created. |
pAppleEvent input: Pointer to an AppleEvent where the |
event record will be returned. |
output: The Apple event. |
RESULT CODES |
____________ |
noErr 0 No error |
memFullErr -108 Not enough room in heap zone |
____________ |
*/ |
extern pascal OSErr MoreAECreateProcessTarget (ProcessSerialNumber *pPSN, AEDesc *target); |
/******************************************************************************** |
Create and return an AppleEvent of the given class and ID. The event will be |
targeted at the current process, with an AEAddressDesc of type |
typeProcessSerialNumber. |
pAEEventClass input: The class of the event to be created. |
pAEEventID input: The ID of the event to be created. |
pAppleEvent input: Pointer to an AppleEvent where the |
event record will be returned. |
output: The Apple event. |
RESULT CODES |
____________ |
noErr 0 No error |
memFullErr -108 Not enough room in heap zone |
____________ |
*/ |
extern pascal OSErr MoreAECreateAppleEventSelfTarget( AEEventClass pAEEventClass, |
AEEventID pAEEventID, |
AppleEvent *pAppleEvent ); |
/******************************************************************************** |
Create and return an AppleEvent of the given class and ID. The event will be |
targeted at the process specified by the target type and creator codes, |
with an AEAddressDesc of type typeProcessSerialNumber. |
pType input: The file type of the process to be found. |
pCreator input: The creator type of the process to be found. |
pAEEventClass input: The class of the event to be created. |
pAEEventID input: The ID of the event to be created. |
pAppleEvent input: Pointer to an AppleEvent where the |
event record will be returned. |
output: The Apple event. |
RESULT CODES |
____________ |
noErr 0 No error |
memFullErr -108 Not enough room in heap zone |
procNotFound Ð600 No eligible process with specified descriptor |
____________ |
*/ |
extern pascal OSErr MoreAECreateAppleEventSignatureTarget( OSType pType, |
OSType pCreator, |
AEEventClass pAEEventClass, |
AEEventID pAEEventID, |
AppleEvent *pAppleEvent ); |
/******************************************************************************** |
Create and return an AppleEvent of the given class and ID. The event will be |
targeted at the application with the specific creator. |
psnPtr input: Pointer to the PSN to target the event with. |
pAEEventClass input: The class of the event to be created. |
pAEEventID input: The ID of the event to be created. |
pAppleEvent input: Pointer to an AppleEvent where the |
event record will be returned. |
output: The Apple event. |
RESULT CODES |
____________ |
noErr 0 No error |
memFullErr -108 Not enough room in heap zone |
procNotFound Ð600 No eligible process with specified descriptor |
____________ |
*/ |
pascal OSStatus MoreAECreateAppleEventCreatorTarget( |
const AEEventClass pAEEventClass, |
const AEEventID pAEEventID, |
const OSType pCreator, |
AppleEvent *pAppleEvent); |
/******************************************************************************** |
Create and return an AppleEvent of the given class and ID. The event will be |
targeted with the provided PSN. |
psnPtr input: Pointer to the PSN to target the event with. |
pAEEventClass input: The class of the event to be created. |
pAEEventID input: The ID of the event to be created. |
pAppleEvent input: Pointer to an AppleEvent where the |
event record will be returned. |
output: The Apple event. |
RESULT CODES |
____________ |
noErr 0 No error |
memFullErr -108 Not enough room in heap zone |
procNotFound Ð600 No eligible process with specified descriptor |
____________ |
*/ |
extern pascal OSErr MoreAECreateAppleEventProcessTarget( const ProcessSerialNumberPtr psnPtr, |
AEEventClass pAEEventClass, |
AEEventID pAEEventID, |
AppleEvent *pAppleEvent ); |
/******************************************************************************** |
Create and return an AppleEvent of the given class and ID. The event will be |
targeted with the provided TargetID. |
pTargetID input: Pointer to the TargetID to target the event with. |
pAEEventClass input: The class of the event to be created. |
pAEEventID input: The ID of the event to be created. |
pAppleEvent input: Pointer to an AppleEvent where the |
event record will be returned. |
output: The Apple event. |
RESULT CODES |
____________ |
noErr 0 No error |
memFullErr -108 Not enough room in heap zone |
procNotFound Ð600 No eligible process with specified descriptor |
____________ |
*/ |
extern pascal OSErr MoreAECreateAppleEventTargetID( const TargetID *pTargetID, |
AEEventClass pAEEventClass, |
AEEventID pAEEventID, |
AppleEvent *pAppleEvent ); |
/******************************************************************************** |
Send the provided AppleEvent using the provided idle function. |
Will wait for a reply if an idle function is provided, but no result will be returned. |
pIdleProcUPP input: The idle function to use when sending the event. |
pAppleEvent input: The event to be sent. |
RESULT CODES |
____________ |
noErr 0 No error |
and any other error that can be returned by AESend or the handler |
in the application that gets the event. |
____________ |
*/ |
extern pascal OSErr MoreAESendEventNoReturnValue( const AEIdleUPP pIdleProcUPP, |
const AppleEvent *pAppleEvent ); |
/******************************************************************************** |
Send the provided AppleEvent using the provided idle function. |
Return data (at pDataPtr) of type pDesiredType |
pIdleProcUPP input: The idle function to use when sending the event. |
pAppleEvent input: The event to be sent. |
theValue output: The value returned by the event. |
RESULT CODES |
____________ |
noErr 0 No error |
paramErr -50 No idle function provided |
and any other error that can be returned by AESend or the handler |
in the application that gets the event. |
____________ |
*/ |
extern pascal OSErr MoreAESendEventReturnData( |
const AEIdleUPP pIdleProcUPP, |
const AppleEvent *pAppleEvent, |
DescType pDesiredType, |
DescType* pActualType, |
void* pDataPtr, |
Size pMaximumSize, |
Size *pActualSize); |
/******************************************************************************** |
Send the provided AppleEvent using the provided idle function. |
Return a SInt16 (typeSmallInteger). |
pIdleProcUPP input: The idle function to use when sending the event. |
pAppleEvent input: The event to be sent. |
theValue output: The value returned by the event. |
RESULT CODES |
____________ |
noErr 0 No error |
paramErr -50 No idle function provided |
and any other error that can be returned by AESend or the handler |
in the application that gets the event. |
____________ |
*/ |
extern pascal OSErr MoreAESendEventReturnSInt16( |
const AEIdleUPP pIdleProcUPP, |
const AppleEvent *pAppleEvent, |
SInt16 *theValue ); |
/******************************************************************************** |
Send the provided AppleEvent using the provided idle function. |
Returns a PString. |
pIdleProcUPP input: The idle function to use when sending the event. |
pAppleEvent input: The event to be sent. |
pStr255 output: The value returned by the event. |
RESULT CODES |
____________ |
noErr 0 No error |
paramErr -50 No idle function provided |
and any other error that can be returned by AESend or the handler |
in the application that gets the event. |
____________ |
*/ |
extern pascal OSErr MoreAESendEventReturnPString( |
const AEIdleUPP pIdleProcUPP, |
const AppleEvent* pAppleEvent, |
Str255 pStr255); |
/******************************************************************************** |
Send an AppleEvent of the specified Class & ID to myself using the |
provided idle function. The actual target of the event is the |
pSelection property of the application. |
pIdleProcUPP input: The idle function to use when sending the event. |
pEventID input: The event to be sent. |
RESULT CODES |
____________ |
noErr 0 No error |
and any other error that can be returned by AESend or the handler |
in the application that gets the event. |
____________ |
*/ |
extern pascal OSErr MoreAESendToSelfNoReturnValue( |
const AEEventClass pEventClass, |
const AEEventID pEventID); |
/******************************************************************************** |
Send an AppleEvent of the specified Class & ID to myself using the |
provided idle function. Wait for a reply and extract a SInt16 result. |
The actual target of the event is the pSelection property of the |
application. |
pIdleProcUPP input: The idle function to use when sending the event. |
pEventID input: The event to be sent. |
pValue Output: Where the return SInt16 will be stored. |
RESULT CODES |
____________ |
noErr 0 No error |
and any other error that can be returned by AESend or the handler |
in the application that gets the event. |
____________ |
*/ |
extern pascal OSErr MoreAESendToSelfReturnSInt16( |
const AEEventClass pEventClass, |
const AEEventID pEventID, |
SInt16* pValue); |
/******************************************************************************** |
Send a get data (kAEGetData) AppleEvent to myself using the |
provided idle function. Wait for a reply and extract a SInt16 result. |
pIdleProcUPP input: The idle function to use when sending the event. |
pEventID input: The event to be sent. |
pValue Output: Where the resulting SInt16 will be stored. |
RESULT CODES |
____________ |
noErr 0 No error |
and any other error that can be returned by AESend or the handler |
in the application that gets the event. |
____________ |
*/ |
extern pascal OSErr MoreAETellSelfToGetSInt16Property( |
const DescType pPropType, |
SInt16* pValue); |
/******************************************************************************** |
Send a get data (kAEGetData) AppleEvent to myself using the |
provided idle function. Wait for a reply and extract a Str255 result. |
The actual target of the event is the pSelection property of the |
application. |
pIdleProcUPP input: The idle function to use when sending the event. |
pEventID input: The event to be sent. |
pValue Output: Where the resulting Str255 will be stored. |
RESULT CODES |
____________ |
noErr 0 No error |
and any other error that can be returned by AESend or the handler |
in the application that gets the event. |
____________ |
*/ |
extern pascal OSErr MoreAETellSelfToGetStr255Property( |
const DescType pPropType, |
Str255 pValue); |
/******************************************************************************** |
Send a set data (kAESetData) AppleEvent to myself with a SInt16 parameter |
and using the provided idle function. |
pIdleProcUPP input: The idle function to use when sending the event. |
pEventID input: The event to be sent. |
pValue Output: Where the resulting SInt16 will be stored. |
RESULT CODES |
____________ |
noErr 0 No error |
and any other error that can be returned by AESend or the handler |
in the application that gets the event. |
____________ |
*/ |
extern pascal OSErr MoreAETellSelfToSetSInt16Property( |
const DescType pPropType, |
SInt16 pValue); |
/******************************************************************************** |
Send a set data (kAESetData) AppleEvent to myself with a SInt16 parameter |
and using the provided idle function. |
pIdleProcUPP input: The idle function to use when sending the event. |
pEventID input: The event to be sent. |
pValue Output: Where the resulting Str255 will be stored. |
RESULT CODES |
____________ |
noErr 0 No error |
and any other error that can be returned by AESend or the handler |
in the application that gets the event. |
____________ |
*/ |
extern pascal OSErr MoreAETellSelfToSetStr255Property( |
const DescType pPropType, |
Str255 pValue); |
//******************************************************************************* |
// Appends each of the items in pSourceList to the pDestList. |
extern pascal OSStatus MoreAEAppendListToList(const AEDescList *pSourceList, AEDescList *pDestList); |
//******************************************************************************* |
// This routine takes a result descriptor and an error. |
// If there is a result to add to the reply it makes sure the reply isn't |
// NULL itself then adds the error to the reply depending on the error |
// and the type of result. |
extern pascal OSErr MoreAEMoreAESetReplyErrorNumber (OSErr pOSErr, AppleEvent *pAEReply); |
//******************************************************************************* |
// This routine takes a result descriptor, a reply descriptor and an error. |
// If there is a result to add to the reply it makes sure the reply isn't |
// NULL itself then adds the result to the reply depending on the error |
// and the type of result. |
extern pascal OSErr MoreAEAddResultToReply(AEDesc* pResult, AEDesc* pAEReply, OSErr error); |
// ---------------------------------------------------------------------- |
// Name: MoreAEGotRequiredParams |
// Function: Checks that all parameters defined as 'required' have been read |
// ---------------------------------------------------------------------- |
extern pascal OSErr MoreAEGotRequiredParams(const AppleEvent *theAppleEvent); |
/******************************************************************************** |
Takes a reply event checks it for any errors that may have been returned |
by the event handler. A simple function, in that it only returns the error |
number. You can often also extract an error string and three other error |
parameters from a reply event. |
Also see: |
IM:IAC for details about returned error strings. |
AppleScript developer release notes for info on the other error parameters. |
pAEReply input: The reply event to be checked. |
RESULT CODES |
____________ |
noErr 0 No error |
???? ?? Pretty much any error, depending on what the |
event handler returns for it's errors. |
*/ |
extern pascal OSErr MoreAEGetHandlerError( const AppleEvent *pAEReply ); |
/******************************************************************************** |
Get the class and ID from an AppleEvent. |
pAppleEvent input: The event to get the class and ID from. |
pAEEventClass output: The event's class. |
pAEEventID output: The event's ID. |
RESULT CODES |
____________ |
noErr 0 No error |
memFullErr -108 Not enough room in heap zone |
errAEDescNotFound -1701 Descriptor record was not found |
errAENotAEDesc -1704 Not a valid descriptor record |
errAEReplyNotArrived -1718 Reply has not yet arrived |
*/ |
extern pascal OSErr MoreAEExtractClassAndID ( const AppleEvent *pAppleEvent, |
AEEventClass *pAEEventClass, |
AEEventID *pAEEventID ); |
/******************************************************************************** |
A very simple idle function. It simply ignors any event it receives, |
returns 30 for the sleep time and nil for the mouse region. |
Your application should supply an idle function that handles any events it |
might receive. This is especially important if your application has any windows. |
Also see: |
IM:IAC for details about idle functions. |
Pending Update Perils technote for more about handling low-level events. |
*/ |
extern pascal Boolean MoreAESimpleIdleFunction( EventRecord *event, |
long *sleepTime, |
RgnHandle *mouseRgn ); |
/******************************************************************************** |
Is the Apple Event Manager present. |
RESULT CODES |
____________ |
true The Apple Event Manager is present |
false It isn't |
*/ |
extern pascal Boolean MoreAEHasAppleEvents(void); |
//******************************************************************************* |
// Did this AppleEvent come from the Finder? |
extern pascal OSErr MoreAEIsSenderFinder (const AppleEvent *pAppleEvent, Boolean *pIsFinder); |
//******************************************************************************* |
// Initialises desc to the null descriptor (typeNull, nil). |
extern pascal void MoreAENullDesc(AEDesc *desc); |
//******************************************************************************* |
// Disposes of desc and initialises it to the null descriptor. |
extern pascal void MoreAEDisposeDesc(AEDesc *desc); |
//******************************************************************************* |
// These routines are only implemented in PreCarbon.o for PowerPC |
// So for 68K we had to write our own versions |
#if TARGET_CPU_68K || !ACCESSOR_CALLS_ARE_FUNCTIONS |
extern pascal Size AEGetDescDataSize( const AEDesc* pAEDesc); |
extern pascal OSErr AEGetDescData( |
const AEDesc* pAEDesc, |
void* pDataPtr, |
Size pMaxSize); |
#endif TARGET_CPU_68K || !ACCESSOR_CALLS_ARE_FUNCTIONS |
/******************************************************************************** |
These are generic routines that are used to extract data of |
different types from descriptor records. |
pAEDesc input: The descriptor we want the data from |
pDestPtr output: Where we want to store the data from this desc. |
pMaxSize input: The maxium amount of data we can store. |
pActualSize output: The actual amount of data stored. |
RESULT CODES |
____________ |
noErr 0 No error |
____________ |
*/ |
extern pascal void MoreAEGetRawDataFromDescriptor(const AEDesc* pAEDesc, |
Ptr pDestPtr, |
Size pMaxSize, |
Size *pActualSize); |
extern pascal OSErr MoreAEGetPStringFromDescriptor(const AEDesc* pAEDesc, StringPtr pStringPtr); |
extern pascal OSErr MoreAEGetCStringFromDescriptor(const AEDesc* pAEDesc, char* pCharPtr); |
extern pascal OSErr MoreAEGetShortFromDescriptor(const AEDesc* pAEDesc, SInt16 *pResult); |
extern pascal OSErr MoreAEGetBooleanFromDescriptor(const AEDesc* pAEDesc,Boolean *pResult); |
extern pascal OSErr MoreAEGetLongFromDescriptor(const AEDesc* pAEDesc, long *pResult); |
extern pascal OSErr MoreAEGetOSTypeFromDescriptor(const AEDesc* pAEDesc, OSType *pResult); |
//******************************************************************************* |
// This routine creates a new handle and puts the contents of the desc |
// in that handle. CarbonÕs opaque AEDescÕs means that we need this |
// functionality a lot. |
extern pascal OSStatus MoreAECopyDescriptorDataToHandle(const AEDesc *desc, Handle *descData); |
//******************************************************************************* |
// This routine returns true if and only if desc is the "missing value" value. |
extern pascal Boolean MoreAEIsMissingValue(const AEDesc *desc); |
//******************************************************************************* |
// This routine creates a descriptor that represents the missing value. |
extern pascal OSStatus MoreAECreateMissingValue(AEDesc *desc); |
#ifdef __cplusplus |
} |
#endif |
Copyright © 2003 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2003-01-14