/*

    File:       AEHelpers.h

    Contains:   Functions to help you when you are building and sending Apple events.

    Written by: Andy Bachorski  

    Copyright:  Copyright © 1996-1999 by 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):

                7/22/1999   Karl Groethe    Updated for Metrowerks Codewarror Pro 2.1

*/

//

// %%%%% need to change calls to object building function to pass a boolean

// %%%%% parameter to control the disposal of descs passed in.

#ifndef AEHELPERS

#define AEHELPERS

//  System includes

#include <AERegistry.h>

#include <AEObjects.h>

#include <AEPackObject.h>

#include <Aliases.h>

#include <Icons.h>

#include <Processes.h>

#include <EPPC.h>

#ifdef __cplusplus

extern "C" {

#endif

// *****************************************************************************

pascal  OSErr   FindProcessBySignature( const OSType targetType,

                                        const OSType targetCreator,

                                              ProcessSerialNumberPtr psnPtr );

/*  The FindProcessBySignature function returns a ProcessSerialNumber

    for a process whose signature (type and creator) matches the input values.

    The ProcessSerialNumber will be kNoProcess is the requested process cannot

    be found. 

    targetType      input:  The file type of the process to be found.

    targetCreator   input:  The creator type of the process to be found.

    psnPtr          input:  Pointer to a ProcessSerialNumber where the

                            process serial number is returned.

                    output: Process serial number.

    RESULT CODES

    ____________

    noErr              0    No error

    procNotFound    Ð600    No eligible process with specified descriptor

    ____________

*/

// *****************************************************************************

pascal  OSErr   AEHMakeAppleEventSignatureTarget( const OSType targetType,

                                                  const OSType targetCreator,

                                                  const AEEventClass eventClass,

                                                  const AEEventID eventID,

                                                        AppleEvent *theEvent );

/*  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.

    targetType      input:  The file type of the process to be found.

    targetCreator   input:  The creator type of the process to be found.

    eventClass      input:  The class of the event to be created.

    eventID         input:  The ID of the event to be created.

    theEvent        input:  Pointer to an AppleEvent record 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  OSErr   AEHMakeEventProcessTarget( const ProcessSerialNumberPtr psnPtr,

                                           const AEEventClass eventClass,

                                           const AEEventID eventID,

                                                 AppleEvent *theEvent );

/*  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.

    eventClass      input:  The class of the event to be created.

    eventID         input:  The ID of the event to be created.

    theEvent        input:  Pointer to an AppleEvent record 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  OSErr   AEHMakeEventTargetID( const TargetID *targetIDPtr,

                                      const AEEventClass eventClass,

                                      const AEEventID eventID,

                                            AppleEvent *theEvent );

// *****************************************************************************

pascal  OSErr   AEHMakeAliasDescFromFSSpec( const FSSpecPtr fssPtr,

                                                  AEDesc *aliasDesc );

/*  Create and return an AEDesc of type typeAlias using the provided FSSpec.

    fssPtr          input:  Pointer to the FSSpec to use.

    theEvent        input:  Pointer to null AEDesc.

                    output: an AEDesc of type typeAlias.

    RESULT CODES

    ____________

    noErr              0    No error    

    paramErr         -50    The value of target or alias parameter, or of

                            both, is NIL, or the alias record is corrupt

    memFullErr      -108    Not enough room in heap zone    

    ____________

*/

// *****************************************************************************

pascal OSErr AEHMakeAliasDesc( const AliasHandle aliasHandle,

                                     AEDesc *aliasDesc );

/*  Create and return an AEDesc of type typeAlias using the provided 

    alias record.

    fssPtr          input:  Handle to an alias record.

    theEvent        input:  Pointer to null AEDesc.

                    output: an AEDesc of type typeAlias.

    RESULT CODES

    ____________

    noErr              0    No error    

    memFullErr      -108    Not enough room in heap zone    

    ____________

*/

// *****************************************************************************

pascal  OSErr   AEHMakeAliasObjectFromFSSpec( const FSSpecPtr fssPtr,

                                                    AEDesc *containerObj,

                                                    AEDesc *aliasObject );

/*

    Given an FSSpec, return an object descriptor containing an alias,

    contained by a null object.

    RESULT CODES

    ____________

    noErr                   0   No error    

    paramErr              -50   The value of target or alias parameter, or of

                                both, is NIL, or the alias record is corrupt

    memFullErr           -108   Not enough room in heap zone    

    errAECoercionFail   -1700   Data could not be coerced to the requested 

                                Apple event data type   

    errAEWrongDataType  -1703   Wrong Apple event data type 

    errAENotAEDesc      -1704   Not a valid descriptor record   

    errAEBadListItem    -1705   Operation involving a list item failed  

    ____________

*/

// *****************************************************************************

pascal  OSErr   AEHMakeAliasObject( const AliasHandle aliasHandle,

                                          AEDesc *containerObj,

                                          AEDesc *aliasObject );

/*

    Given an object descriptor, create an new object descriptor containing an

    alias, contained by the input object descriptor.

    RESULT CODES

    ____________

    noErr                   0   No error    

    paramErr              -50   Error in parameter list

    memFullErr           -108   Not enough room in heap zone    

    errAECoercionFail   -1700   Data could not be coerced to the requested 

                                Apple event data type   

    errAEWrongDataType  -1703   Wrong Apple event data type 

    errAENotAEDesc      -1704   Not a valid descriptor record   

    errAEBadListItem    -1705   Operation involving a list item failed  

    ____________

*/

// *****************************************************************************

pascal  OSErr   AEHMakePropertyObject( const DescType propType,

                                             AEDesc *containerObj,

                                             AEDesc *propertyObj );

/*

    Given an object descriptor, create an new object descriptor containing

    an property, contained by the input object descriptor.

    RESULT CODES

    ____________

    noErr                   0   No error    

    paramErr              -50   Error in parameter list

    memFullErr           -108   Not enough room in heap zone    

    errAECoercionFail   -1700   Data could not be coerced to the requested 

                                Apple event data type   

    errAEWrongDataType  -1703   Wrong Apple event data type 

    errAENotAEDesc      -1704   Not a valid descriptor record   

    errAEBadListItem    -1705   Operation involving a list item failed  

    ____________

*/

// *****************************************************************************

pascal  OSErr   AEHMakeProcessObject( const ProcessSerialNumber *psnPtr,

                                             AEDesc *containerObj,

                                             AEDesc *propertyObj );

// *****************************************************************************

pascal  OSErr   AEHMakeSelectionObject( const DescType selection,

                                              AEDesc *containerObj,

                                              AEDesc *propertyObj );

/*

    Given an object descriptor, create an new object descriptor containing

    a selection object using the selection specifier, contained by the 

    input object descriptor.

    RESULT CODES

    ____________

    noErr                   0   No error    

    paramErr              -50   Error in parameter list

    memFullErr           -108   Not enough room in heap zone    

    errAECoercionFail   -1700   Data could not be coerced to the requested 

                                Apple event data type   

    errAEWrongDataType  -1703   Wrong Apple event data type 

    errAENotAEDesc      -1704   Not a valid descriptor record   

    errAEBadListItem    -1705   Operation involving a list item failed  

    __________

*/

// *****************************************************************************

pascal  OSErr   AEHMakeIconSuite( const AEDescList *iconFamilyRecPtr,

                                        Handle *iconSuitePtr );

// *****************************************************************************

pascal  OSErr   AEHMakeIconFamilyRecord( const Handle iconSuite,

                                         const IconSelectorValue iconSelector,

                                               AEDescList *iconFamilyRecPtr );

/*  ¦ Make an icon family record containing the icons specified in the

    iconSelector parameter.

    The iconSuite parameter should contain an icon suite, as returned by a

    call to GetIconSuite.

    iconSuite           input:  The icon suite to build the record from.

    iconSelector        input:  Which icons to include in the record.

    iconFamilyRecPtr    input:  A null descriptor record.

                        output: An AERecord that's been coerced to an

                                icon family record.

    Result Codes

    ____________

    noErr                   0   No error    

    paramErr              -50   The value of target or alias parameter, or of

                                both, is NIL, or the alias record is corrupt

    memFullErr           -108   Not enough room in heap zone    

    errAECoercionFail   -1700   Data could not be coerced to the requested 

                                Apple event data type   

    ____________

    Also see:

*/

// *****************************************************************************

pascal  OSErr   AEHGetHandlerError( const AppleEvent *reply );

/*

    Given a reply event, checks for errors returned by the event handler,

    and returns any that are found.

    reply               input:  The reply event to be checked.

    RESULT CODES

    ____________

    noErr                   0   No error    

    paramErr              -50   The value of target or alias parameter, or of

                                both, is NIL, or the alias record is corrupt

    memFullErr           -108   Not enough room in heap zone    

    errAECoercionFail   -1700   Data could not be coerced to the requested 

                                Apple event data type   

    errAEWrongDataType  -1703   Wrong Apple event data type 

    errAENotAEDesc      -1704   Not a valid descriptor record   

    errAEBadListItem    -1705   Operation involving a list item failed

    ????                Pretty much any error, depending on what the handler

                        of the event sent does.

    ____________

*/

// *****************************************************************************

pascal  Boolean AEHSimpleIdleFunction( EventRecord *event,

                                      long *sleepTime,

                                      RgnHandle *mouseRgn );

/*

    A very simple idle function. It simply ignors an event it receives,

    returns 30 for the sleep time and nil for the mouse region.

    Your application would normally supply a more robust idle function,

    especially if you have any window. See the tech note on Pending Update

    Perils.

*/  

// *****************************************************************************

pascal  Boolean HasAppleEvents( void );

/*

    Calls Gestalt and checks if the Apple Event Manager is available.

    Use this routine together with FinderCallsAEProcess to determine which

    suite of events the Finder supports. If FinderCallsAEProcess returns false

    the Finder supports the subset of the older Finder event suite.

    RESULT CODES

    ____________

    true    The Apple Event Manager is present

    false   It isn't

*/

// *****************************************************************************

pascal  Boolean FinderCallsAEProcess( void );

/*

    Calls Gestalt and checks if the Finder calls AEProcessAppleEvent.

    If true, the Finder is version 7.1.3 or later.

    Use this routine together with FinderIsOSLCompliant to determine which

    suite of events the Finder supports. If FinderIsOSLCompliant returns false

    the Finder supports the full older Finder event suite.

    RESULT CODES

    ____________

    true    The Finder calls supports the full old Finder event suite

    false   It doesn't

*/

// *****************************************************************************

pascal  Boolean FinderIsOSLCompliant( void );

/*

    Calls Gestalt and checks if the Finder is OSL compliant, i.e., it supports

    the new Finder event suite.

    If true, the Finder is version 7.5 or later. This means the Finder supports,

    and that you should use, the new Finder event suite. It also means that 

    support for the events present in old Finder event suite is either missing

    or incomplete.

    RESULT CODES

    ____________

    true    The Finder supports the new Finder event suite, not the old

    false   It doesn't

*/

// *****************************************************************************

#ifdef __cplusplus

}

#endif

#ifndef COMPILING_MORE_FINDER_EVENTS

    #undef pascal

#endif

#endif// AEHELPERS