/*

    File:       ScriptSupport.h

    Description:

    General routines for handling the details involved in calling AppleScript

    script handlers from C.  These routines are not tied to any particular script,

    so they have been spared out from the rest in this general utility file.

    Author:     JM

    Copyright:  Copyright (c) 2003 Apple Computer, Inc. All rights reserved.

    Disclaimer: IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.

                ("Apple") in consideration of your agreement to the following terms, and your

                use, installation, modification or redistribution of this Apple software

                constitutes acceptance of these terms.  If you do not agree with these terms,

                please do not use, install, modify or redistribute this Apple software.

                In consideration of your agreement to abide by the following terms, and subject

                to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs

                copyrights in this original Apple software (the "Apple Software"), to use,

                reproduce, modify and redistribute the Apple Software, with or without

                modifications, in source and/or binary forms; provided that if you redistribute

                the Apple Software in its entirety and without modifications, you must retain

                this notice and the following text and disclaimers in all such redistributions of

                the Apple Software.  Neither the name, trademarks, service marks or logos of

                Apple Computer, Inc. may be used to endorse or promote products derived from the

                Apple Software without specific prior written permission from Apple.  Except as

                expressly stated in this notice, no other rights or licenses, express or implied,

                are granted by Apple herein, including but not limited to any patent rights that

                may be infringed by your derivative works or by other works in which the Apple

                Software may be incorporated.

                The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO

                WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED

                WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR

                PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN

                COMBINATION WITH YOUR PRODUCTS.

                IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR

                CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE

                GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

                ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION

                OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT

                (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN

                ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    Change History (most recent first):

        Fri, Aug 29, 2000 -- created

*/

#ifndef __SCRIPTSUPPORT__

#define __SCRIPTSUPPORT__

#include <Carbon/Carbon.h>

    /* General routines for handling the details involved in calling AppleScript

    script handlers from C.  These routines are not tied to any particular script,

    so they have been spared out from the rest in this general utility file. */

    /* LoadedScriptInfo saves the persistent state information used by the

    LoadCompiledScript, CallScriptSubroutine, and UnloadCompiledScript routines.  */

typedef struct {

    ComponentInstance fComponent; /* scripting component */

    OSAID fContextID; /* compiled script's context ID */

} LoadedScriptInfo, *LoadedScriptInfoPtr;

    /* LoadCompiledScript loads the compiled script in the resource file named

    scriptRName with the extension .scpt.  The script is prepared and all of the

    state information required to call subroutines in the script is saved in the

    scriptInfo record that is returned.  Later, when you call subroutines you

    defined in that script, you will pass scriptInfo to the CallScriptSubroutine

    that uses this information to call the script's subroutines. */

OSStatus LoadCompiledScript(CFStringRef scriptRName, LoadedScriptInfoPtr *scriptInfo);

    /* UnloadCompiledScript releases all of the information in the scriptInfo structure.

    Call this routine when you are done using a scriptInfo structure returned by

    LoadCompiledScript.  */

void UnloadCompiledScript( LoadedScriptInfoPtr scriptInfo );

    /* CallScriptSubroutine is used for calling script handlers that are in a compiled

    script loaded by LoadCompiledScript.  you provide the script reference loaded by

    LoadCompiledScript, the name of the handler you would like to execute, and a list

    of parameters to be passed to the subroutine.  Any data returned by the script

    handler will be placed in the resultData descriptor (if you provide one), and

    any errors generated will be described as text (when possible) in the error

    messaged descriptor (if you provide one).  */

OSStatus CallScriptSubroutine(

                LoadedScriptInfoPtr scriptInfo, /* returned by LoadCompiledScript */

                char* subroutineName, /* the name off the subroutine - must be all lowercase */

                AEDescList *subroutineParameters, /* positionally ordered list of parameters */

                AEDesc *resultData, /* returned data from the script - can be NULL */

                AEDesc *errorMessages /* error messages - can be NULL */

                );

    /* AEBuildErrorToAEDesc converts an AEBuildError error descriptor into

    a unicode text AEDesc.  If an error occurs, then the descriptor is

    initialized to a typeNull desc. This is a utility routine for finding

    problems in your AEBuild strings. */

void AEBuildErrorToAEDesc(AEBuildError *error, AEDesc *errorTextDesc);

    /* The following conversion routines are here mostly for illustration

    showing how to convert different types to AEDesc records that

    you can pass to scripts as parameters or from AEDesc records that you

    receive from scripts as results.  In some cases, the implementation is

    trivial, though they are included because the discovery of the trivial

    implementation may not necessairly be so. */

    /* AEDescToAlias and AliasToAEDesc are convenience routines for

    converting AliasHandles to and from AEDesc records */

OSStatus AEDescToAlias( AEDesc *aliasDesc, AliasHandle *theAlias );

OSStatus AliasToAEDesc( AliasHandle theAlias, AEDesc *theAliasDesc  );

    /* AEDescToCFString and CFStringToAEDesc are convenience routines for

    converting CFStringRefs to and from AEDesc records */

OSStatus AEDescToCFString( AEDesc *stringDescriptor, CFStringRef *theString );

OSStatus CFStringToAEDesc( CFStringRef theString, AEDesc *theUnicodeDesc );

    /* AEDescToBoolean and BooleanToAEDesc are convenience routines for

    converting Boolean values to and from AEDesc records */

OSStatus AEDescToBoolean( AEDesc *boolDesc, Boolean *theValue );

OSStatus BooleanToAEDesc( Boolean theValue, AEDesc *theBoolDesc  );

    /* AEDescToLong and LongToAEDesc are convenience routines for

    converting integer values to and from AEDesc records */

OSStatus AEDescToLong( AEDesc *longDesc, long *theValue );

OSStatus LongToAEDesc( long theValue, AEDesc *theLongDesc );

#endif