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.
MIB Bits/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-03-14