Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

OSA(3)                               User Contributed Perl Documentation                              OSA(3)



NAME
       Mac::OSA - Provide interface to Open Scripting Architecture

SYNOPSIS
           use Mac::OSA;

           use Mac::OSA qw(OSALoad OSAStore OSAExecute);

DESCRIPTION
       Access to Inside Macintosh is essential for proper use of these functions.  Explanations of terms,
       processes and procedures are provided there.  Any attempt to use these functions without guidance can
       cause severe errors in your machine, including corruption of data. You have been warned.

   Constants
       kOSAComponentType
       kOSAGenericScriptingComponentSubtype
       kOSAFileType
       kOSASuite
       kOSARecordedText
       kOSAScriptIsModified
       kOSAScriptIsTypeCompiledScript
       kOSAScriptIsTypeScriptValue
       kOSAScriptIsTypeScriptContext
       kOSAScriptBestType
       kOSACanGetSource
       typeOSADialectInfo
       keyOSADialectName
       keyOSADialectCode
       keyOSADialectLangCode
       keyOSADialectScriptCode
       kOSAScriptResourceType
       typeOSAGenericStorage
           Types and keywords.

       kOSANullScript
       kOSANullMode
       kOSAModeNull
           Default values.

       kOSASupportsCompiling
       kOSASupportsGetSource
       kOSASupportsAECoercion
       kOSASupportsAESending
       kOSASupportsRecording
       kOSASupportsConvenience
       kOSASupportsDialects
       kOSASupportsEventHandling
           Feature flags.

       kOSAModePreventGetSource
       kOSAModeNeverInteract
       kOSAModeCanInteract
       kOSAModeAlwaysInteract
       kOSAModeDontReconnect
       kOSAModeCantSwitchLayer
       kOSAModeDoRecord
       kOSAModeCompileIntoContext
       kOSAModeAugmentContext
       kOSAModeDisplayForHumans
       kOSAModeDontStoreParent
       kOSAModeDispatchToDirectObject
       kOSAModeDontGetDataForArguments
       kOSAModeDontDefine
           Mode flags.

       kOSAErrorNumber
       kOSAErrorMessage
       kOSAErrorBriefMessage
       kOSAErrorApp
       kOSAErrorPartialResult
       kOSAErrorOffendingObject
       kOSAErrorExpectedType
       kOSAErrorRange
       typeOSAErrorRange
       keyOSASourceStart
       keyOSASourceEnd
           Error handling.

       kOSAUseStandardDispatch
       kOSANoDispatch
       kOSADontUsePhac
       kGenericComponentVersion
           Dispatching flags

   Functions
       OSALoad SCRIPTINGCOMPONENT, SCRIPTDATA, MODEFLAGS
           The OSALoad function loads script data and returns a script ID. The generic scripting component
           uses the descriptor record in the SCRIPTDATA parameter to determine which scripting component
           should load the script. If the descriptor record is of type typeOSAGenericStorage, the generic
           scripting component uses the trailer at the end of the SCRIPTDATA to identify the scripting
           component. If the descriptor record's type is the subtype value for another scripting component,
           the generic scripting component uses the descriptor type to identify the scripting component.
           Return "undef" if an error was detected.

       OSAStore SCRIPTINGCOMPONENT, SCRIPTID, DESIREDTYPE, MODEFLAGS
           The OSAStore function returns script data in a descriptor record so that the data can later be
           saved in a resource or written to the data fork of a document. You can then reload the data for
           the descriptor record as a compiled script (although possibly with a different script ID) by
           passing the descriptor record to OSALoad().  Return "undef" if an error was detected.

       OSAExecute SCRIPTINGCOMPONENT, COMPILEDSCRIPTID, CONTEXTID, MODEFLAGS
           The OSAExecute function executes the compiled script identified by the COMPILEDSCRIPTID
           parameter, using the script context identified by the CONTEXTID parameter to maintain state
           information, such as the binding of variables, for the compiled script. After successfully
           executing a script, OSAExecute returns the script ID for a resulting script value, or, if
           execution does not result in a value, "undef".

       OSADisplay SCRIPTINGCOMPONENT, SCRIPTVALUEID, DESIREDTYPE, MODEFLAGS
           The OSADisplay function coerces the script value identified by SCRIPTVALUEID to a descriptor
           record of the text type specified by the DESIREDTYPE parameter, if possible. Valid types include
           all the standard text descriptor types defined in the Apple Event Registry: Standard Suites, plus
           any special types supported by the scripting component.  Return "undef" if an error was detected.

       OSAScriptError SCRIPTINGCOMPONENT, SELECTOR, DESIREDTYPE
           Whenever the OSAExecute() function returns the error errOSAScriptError, you can use the
           OSAScriptError function to get more specific information about the error from the scripting
           component that encountered it. (This information remains available only until the next call to
           the same scripting component.) The information returned by OSAScriptError depends on the value
           passed in the SELECTOR parameter, which also determines the descriptor type you should specify in
           the DESIREDTYPE parameter.

           Return "undef" if an error was detected.

       OSADispose SCRIPTINGCOMPONENT, SCRIPTID
           The OSADispose function releases the memory assigned to the script data identified by the
           SCRIPTID parameter. The SCRIPTID passed to the OSADispose function is no longer valid if the
           function returns successfully. A scripting component can then reuse that SCRIPTID for other
           script data.  Return zero if no error was detected.

       OSASetScriptInfo SCRIPTINGCOMPONENT, SCRIPTID, SELECTOR, VALUE
           The OSASetScriptInfo function sets script information according to the value you pass in the
           selector parameter. If you use the kOSAScriptIsModified constant, OSASetScriptInfo sets a value
           that indicates how many times the script data has been modified since it was created or passed to
           OSALoad. Some scripting components may provide additional constants.  Return zero if no error was
           detected.

       OSAGetScriptInfo SCRIPTINGCOMPONENT, SCRIPTID, SELECTOR
           The OSAGetScriptInfo function returns various results according to the value you pass in the
           SELECTOR parameter.  Returns an integer value which may need to be recast as the desired type.

       OSASetProperty SCRIPTINGCOMPONENT, MODEFLAGS, SCRIPTID, VARIABLENAME, SCRIPTVALUEID
           The OSASetProperty function sets the value of a script property in a specified script.
           VARIABLENAME is an AEDesc.

       OSAGetProperty SCRIPTINGCOMPONENT, MODEFLAGS, SCRIPTID, VARIABLENAME
           The OSAGetProperty function gets the value of a script property in a specified script.
           VARIABLENAME is an AEDesc.  Returns an AEDesc.

       OSAGetAppTerminology SCRIPTINGCOMPONENT, MODEFLAGS, FILE, TERMINOLOGYID
           OSAGetAppTerminology gets one or more scripting terminology resources from the specified file.
           Returns an AEDesc.

       OSAScriptingComponentName SCRIPTINGCOMPONENT
           The OSAScriptingComponentName function returns a descriptor record that you can coerce to a text
           descriptor type such as typeChar. This can be useful if you want to display the name of the
           scripting language in which the user should write a new script.  Return "undef" if an error was
           detected.

       OSACompile SCRIPTINGCOMPONENT, SOURCEDATA, MODEFLAGS, [PREVIOUSSCRIPTID]
           You can pass a descriptor record containing source data suitable for a specific scripting
           component (usually text) to the OSACompile function to obtain a script ID for the equivalent
           compiled script or script context. To compile the source data as a script context for use with
           OSAExecuteEvent() or OSADoEvent(), you must set the kOSAModeCompileIntoContext flag, and the
           source data should include appropriate handlers.  Return zero if no error was detected.

       OSACopyID SCRIPTINGCOMPONENT, FROMID, [TOID]
           The OSACopyID function replaces the script data identified by the script ID in the TOID parameter
           with the script data identified by the script ID in the FROMID parameter.  Return "undef" if an
           error was detected.

       OSAGetSource SCRIPTINGCOMPONENT, SCRIPTID, [DESIREDTYPE]
           The OSAGetSource function decompiles the script data identified by the specified script ID and
           returns a descriptor record containing the equivalent source data.  Return "undef" if an error
           was detected.

       OSACoerceFromDesc SCRIPTINGCOMPONENT, SCRIPTDATA, MODEFLAGS
           The OSACoerceFromDesc function coerces the descriptor record in the SCRIPTDATA parameter to the
           equivalent script value and returns a script ID for that value.  Return "undef" if an error was
           detected.

       OSACoerceToDesc SCRIPTINGCOMPONENT, SCRIPTID, DESIREDTYPE, MODEFLAGS
           The OSACoerceToDesc function coerces the script value identified by SCRIPTID to a descriptor
           record of the type specified by the DESIREDTYPE parameter, if possible.  Return "undef" if an
           error was detected.

       OSASetDefaultTarget SCRIPTINGCOMPONENT, TARGET
           The OSASetDefaultTarget function establishes the default target application for Apple event
           sending and the default application from which the scripting component should obtain terminology
           information. For example, AppleScript statements that refer to the default application do not
           need to be enclosed in "tell/end tell" statements.  Return zero if no error was detected.

       OSAStartRecording SCRIPTINGCOMPONENT, [COMPILEDSCRIPTTOMODIFYID]
           The OSAStartRecording routine turns on Apple event recording. Subsequent Apple events are
           recorded (that is, appended to any existing statements) in the compiled script specified by the
           COMPILEDSCRIPTTOMODIFYID parameter.  Return "undef" if an error was detected.

       OSAStopRecording SCRIPTINGCOMPONENT, COMPILEDSCRIPTID
           The OSAStopRecording function turns off recording. If the script is not currently open in a
           script editor window, the COMPILEDSCRIPTTOMODIFYID parameter supplied to OSAStartRecording() is
           then augmented to contain the newly recorded statements.  If the script is currently open in a
           script editor window, the script data that corresponds to the compiledScriptToModifyID parameter
           supplied to OSAStartRecording() is updated continuously until the client application calls
           OSAStopRecording.  Return zero if no error was detected.

       OSALoadExecute SCRIPTINGCOMPONENT, SCRIPTDATA, CONTEXTID, MODEFLAGS
           The OSALoadExecute function loads script data and executes the resulting compiled script, using
           the script context identified by the CONTEXTID parameter to maintain state information such as
           the binding of variables. After successfully executing the script, OSALoadExecute disposes of the
           compiled script and returns either the script ID for the resulting script value or, if execution
           does not result in a value, the constant kOSANullScript.  Return "undef" if an error was
           detected.

       OSACompileExecute SCRIPTINGCOMPONENT, SOURCEDATA, CONTEXTID, MODEFLAGS
           The OSACompileExecute function compiles source data and executes the resulting compiled script,
           using the script context identified by the CONTEXTID parameter to maintain state information such
           as the binding of variables. After successfully executing the script, OSACompileExecute disposes
           of the compiled script and returns either the script ID for the resulting script value or, if
           execution does not result in a value, the constant kOSANullScript.  Return "undef" if an error
           was detected.

       OSADoScript SCRIPTINGCOMPONENT, SOURCEDATA, CONTEXTID, DESIREDTYPE, MODEFLAGS
           Calling the OSADoScript function is equivalent to calling OSACompile() followed by OSAExecute()
           and OSADisplay(). After compiling the source data, executing the compiled script using the script
           context identified by the CONTEXTID parameter, and returning the text equivalent of the resulting
           script value, OSADoScript disposes of both the compiled script and the resulting script value.
           Return "undef" if an error was detected.

       OSASetCurrentDialect SCRIPTINGCOMPONENT, DIALECTCODE
           Set the current dialect for a scripting component.  Return zero if no error was detected.

       OSAGetCurrentDialect SCRIPTINGCOMPONENT
           Get the dialect code for the dialect currently being used by a scripting component.  Returns the
           code for the current dialect of the specified scripting component.

       OSAAvailableDialects SCRIPTINGCOMPONENT
           Obtain a descriptor list containing information about each of the currently available dialects
           for a scripting component.  Return "undef" if an error was detected.

       OSAGetDialectInfo SCRIPTINGCOMPONENT, DIALECTCODE, SELECTOR
           After you obtain a list of dialect codes by calling OSAAvailableDialectCodeList(), you can pass
           any of those codes to OSAGetDialectInfo to get information about the corresponding dialect. The
           descriptor type of the descriptor record returned by OSAGetDialectInfo depends on the constant
           specified in the SELECTOR parameter.  Return "undef" if an error was detected.

       OSAAvailableDialectCodeList SCRIPTINGCOMPONENT
           Obtain a descriptor list containing dialect codes for each of a scripting component's currently
           available dialects.  Return "undef" if an error was detected.

       OSAExecuteEvent SCRIPTINGCOMPONENT, THEAPPLEEVENT, CONTEXTID, MODEFLAGS
           The OSAExecuteEvent function attempts to use the script context specified by the contextID
           parameter to handle the Apple event specified by the THEAPPLEEVENT parameter.  Return "undef" if
           an error was detected.

       OSADoEvent SCRIPTINGCOMPONENT, THEAPPLEEVENT, CONTEXTID, MODEFLAGS
           The OSADoEvent function resembles both OSADoScript() and OSAExecuteEvent().  However, unlike
           OSADoScript(), the script OSADoEvent executes must be in the form of a script context, and
           execution is initiated by an Apple event. Unlike OSAExecuteEvent(), OSADoEvent returns a reply
           Apple event rather than the script ID of the resulting script value.  Return "undef" if an error
           was detected.

       OSAMakeContext SCRIPTINGCOMPONENT, CONTEXTNAME, [PARENTCONTEXT]
           The OSAMakeContext function creates a new script context that you may pass to OSAExecute() or
           OSAExecuteEvent(). The new script context inherits the bindings of the script context specified
           in the PARENTCONTEXT parameter.  Return "undef" if an error was detected.

       OSAGetDefaultScriptingComponent GENERICSCRIPTINGCOMPONENT
           The OSAGetDefaultScriptingComponent function returns the subtype code for the default scripting
           component. This is the scripting component that will be used by OSAStartRecording(),
           OSACompile(), or OSACompileExecute() if no existing script ID is specified. From the user's point
           of view, the default scripting component corresponds to the scripting language selected in the
           Script Editor application when the user first creates a new script.  Return "undef" if an error
           was detected.

       OSASetDefaultScriptingComponent GENERICSCRIPTINGCOMPONENT, SCRIPTINGSUBTYPE
           The OSASetDefaultScriptingComponent function sets the default scripting component for the
           specified instance of the generic scripting component to the scripting component identified by
           the SCRIPTINGSUBTYPE parameter.  Return zero if no error was detected.

       OSAGetScriptingComponent GENERICSCRIPTINGCOMPONENT, SCRIPTINGSUBTYPE
           The OSAGetScriptingComponent function returns an instance of the scripting component identified
           by the SCRIPTINGSUBTYPE parameter. Each instance of the generic scripting component keeps track
           of a single instance of each component subtype, so OSAGetScriptingComponent always returns the
           same instance of a specified scripting component that the generic scripting component uses for
           standard scripting component routines.  Return "undef" if an error was detected.

       OSAGetScriptingComponentFromStored GENERICSCRIPTINGCOMPONENT, SCRIPTDATA
           The OSAGetScriptingComponentFromStored function returns the subtype code for the scripting
           component that created the script data specified by the SCRIPTDATA parameter.  Return "undef" if
           an error was detected.

       OSAGenericToRealID GENERICSCRIPTINGCOMPONENT, GENERICSCRIPTID
           Given a GENERICSCRIPTID (that is, a script ID returned by a call to a standard component routine
           via the generic scripting component), the OSAGenericToRealID function returns the equivalent
           component-specific script ID and the component instance that created that script ID as an array.

       OSARealToGenericID GENERICSCRIPTINGCOMPONENT, THESCRIPTID, THEEXACTCOMPONENT
           The OSARealToGenericID function performs the reverse of the task performed by
           OSAGenericToRealID(). Given a component-specific SCRIPTID and an exact scripting component
           instance (that is, the component instance that created the component-specific script ID), the
           OSARealToGenericID function returns the corresponding generic script ID.  Return "undef" if an
           error was detected.

AUTHOR
       Written by Matthias Ulrich Neeracher <neeracher@mac.com>, documentation by Bob Dalgleish
       <bob.dalgleish@sasknet.sk.ca>.  Currently maintained by Chris Nandor <pudge@pobox.com>.



perl v5.12.5                                     2013-08-25                                           OSA(3)