/*

    File:       MoreAEObjects.h

    Contains:   Functions to help you when you are working with Apple event objects.

    Written by: George Warner

    Copyright:  Copyright (c) 2000 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):

         <2>      9/3/00    Quinn   Fix initial checkin problem.

         <1>      3/9/00    GW      Integrating AppleEvent Helper code. First Check In.

*/

#pragma once

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

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

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

//  A private conditionals file to setup the build environment for this project.

#include "MoreSetup.h"

//**********    Universal Headers       ****************************************

#include <AERegistry.h>

#include <AEObjects.h>

#include <AEPackObject.h>

#include <Aliases.h>

#include <Icons.h>

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

#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

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

    Add a parameter of type typeAlias to an AERecord (or AppleEvent) using the provided FSSpec.

    pFSSpec         input:  Pointer to the FSSpec to use.

    pKeyword        input:  The key for the data to be added to the record.

    pAERecord       input:  Pointer to the record (or event) to add the data to.

    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    

*/

extern pascal   OSErr   MoreAEOAddAliasParameterFromFSSpec(const FSSpecPtr pFSSpec,

                                                const DescType pKeyword,

                                                AERecord *pAERecord );

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

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

    pFSSpec         input:  Pointer to the FSSpec to use.

    pAliasAEDesc    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    

*/

extern pascal   OSErr   MoreAEOCreateAliasDescFromFSSpec( const FSSpecPtr pFSSpec,

                                                  AEDesc *pAliasAEDesc );

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

    Create and return an AEDesc of type typeAlias using the provided 

    alias record.

    aliasHandle     input:  Handle to an alias record.

    pAliasAEDesc    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    

*/

extern pascal OSErr MoreAEOCreateAliasDesc( const AliasHandle aliasHandle,

                                     AEDesc *pAliasAEDesc );

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

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

    contained by containerObj.

    pFSSpec         input:  Pointer to the FSSpec to use.

    containerObjPtr input:  Pointer to container object for object being created.

    aliasObjectPtr  input:  Pointer to null AEDesc.

                    output: an alias 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  

*/

extern pascal   OSErr   MoreAEOCreateAliasObjectFromFSSpec( const FSSpecPtr pFSSpec,

                                                    AEDesc *containerObjPtr,

                                                    AEDesc *aliasObjectPtr );

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

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

    contained by containerObj.

    aliasHandle     input:  Handle to an alias record.

    containerObjPtr input:  Pointer to container object for object being created.

    aliasObjectPtr  input:  Pointer to null AEDesc.

                    output: an alias object.

    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  

*/

extern pascal   OSErr   MoreAEOCreateAliasObject( const AliasHandle aliasHandle,

                                          AEDesc *containerObjPtr,

                                          AEDesc *aliasObjectPtr );

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

    Given a property type, create an new object descriptor for that property,

    contained by containerObj.

    propType        input:  Property type to use for object.

    containerObjPtr input:  Pointer to container object for object being created.

    propertyObjPtr  input:  Pointer to null AEDesc.

                    output: A property object.

    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  

*/

extern pascal   OSErr   MoreAEOCreatePropertyObject( const DescType propType,

                                             AEDesc *containerObjPtr,

                                             AEDesc *propertyObjPtr );

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

    Given a ProcessSerialNumber, create an new object descriptor for the PSN,

    contained by containerObj.

    psnPtr          input:  ProcessSerialNumber to use for object.

    containerObjPtr input:  Pointer to container object for object being created.

    psnObjPtr       input:  Pointer to null AEDesc.

                    output: A ProcessSerialNumber object.

    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  

*/

extern pascal   OSErr   MoreAEOCreateProcessObject( const ProcessSerialNumber *psnPtr,

                                            AEDesc *containerObjPtr,

                                            AEDesc *psnObjPtr );

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

    Given selection type, create an new object descriptor for a selection,

    contained by containerObj.

    selection       input:  Selection type to use for object.

    containerObjPtr input:  Pointer to container object for object being created.

    selectionObject input:  Pointer to null AEDesc.

                    output: A property object.

    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  

*/

extern pascal   OSErr   MoreAEOCreateSelectionObject( const DescType selection,

                                              AEDesc *containerObjPtr,

                                              AEDesc *selectionObject );

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

    Make position list (a list containing two longs representin the x and y values

    for the position of a Finder item).

    position            input:  A point specifying the position.

    pPositionAEList     input:  Pointer to an AEList (contents will be lost, but not disposed).

                        output: A new AEList containing the x & y values for the position.

    Result Codes

    ____________

    noErr                   0   No error    

    memFullErr           -108   Not enough room in heap zone    

*/

extern pascal   OSErr   MoreAEOCreatePositionList( const Point position,

                                     AEDescList *pPositionAEList );

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

// A simple wrapper around CreateObjSpecifier which creates

// an object specifier using formUniqueID and the unique ID

// in pKeyData.

pascal OSStatus MoreAEOCreateObjSpecifierFormUniqueID(DescType pDesiredClass, const AEDesc *pContainer, 

                                                SInt32 pKeyData, Boolean pDisposeInputs, 

                                                AEDesc *pObjSpecifier);

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

// A simple wrapper around CreateObjSpecifier which creates

// an object specifier using formAbsolutePosition, a key of

// typeLongInteger (rather than typeAbsoluteOrdinal) and the

// position index in pKeyData.

pascal OSStatus MoreAEOCreateObjSpecifierFormAbsPos(DescType pDesiredClass, const AEDesc *pContainer, 

                                            SInt32 pKeyData, SInt32 pDisposeInputs, 

                                            AEDesc *pObjSpecifier);

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

// A simple wrapper around CreateObjSpecifier which creates

// an object specifier using formName and the name in pKeyData.

pascal OSStatus MoreAEOCreateObjSpecifierFormName(DescType pDesiredClass, const AEDesc *pContainer, 

                                            ConstStr255Param pKeyData, Boolean pDisposeInputs, 

                                            AEDesc *pObjSpecifier);

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

#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