objc2_scripting_bridge/generated/

SBApplication.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
use objc2::__framework_prelude::*;
#[cfg(feature = "objc2-core-services")]
use objc2_core_services::*;
use objc2_foundation::*;

use crate::*;

extern_class!(
    /// The `SBApplication` class provides a mechanism enabling an Objective-C
    /// program to send Apple events to a scriptable application and receive Apple
    /// events in response. It thereby makes it possible for that program to control
    /// the application and exchange data with it. Scripting Bridge works by
    /// bridging data types between Apple event descriptors and Cocoa objects.
    ///
    /// Although `SBApplication` includes methods that manually send and process
    /// Apple events, you should never have to call these methods directly. Instead,
    /// subclasses of `SBApplication` implement application-specific methods that
    /// handle the sending of Apple events automatically.
    ///
    /// For example, if you wanted to get the current iTunes track, you can simply
    /// use the `currentTrack` method of the dynamically defined subclass for the
    /// iTunes application—which handles the details of sending the Apple event for
    /// you—rather than figuring out the more complicated, low-level alternative:
    ///
    /// ```objc
    /// [iTunes propertyWithCode:'pTrk'];
    /// ```
    ///
    /// If you do need to send Apple events manually, consider using the
    /// `NSAppleEventDescriptor` class.
    ///
    /// ## Subclassing Notes
    ///
    /// You rarely instantiate `SBApplication` objects directly. Instead, you get
    /// the shared instance of a application-specific subclass typically by calling
    /// one of the `applicationWith...` class methods, using a bundle identifier,
    /// process identifier, or URL to identify the application.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/scriptingbridge/sbapplication?language=objc)
    #[unsafe(super(SBObject, NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    #[cfg(feature = "SBObject")]
    pub struct SBApplication;
);

#[cfg(feature = "SBObject")]
extern_conformance!(
    unsafe impl NSCoding for SBApplication {}
);

#[cfg(feature = "SBObject")]
extern_conformance!(
    unsafe impl NSObjectProtocol for SBApplication {}
);

#[cfg(feature = "SBObject")]
impl SBApplication {
    extern_methods!(
        /// Returns an instance of an `SBApplication` subclass that represents the
        /// target application identified by the given bundle identifier.
        ///
        /// If you must initialize an `SBApplication` object explictly, you should use
        /// this initializer if possible; unlike
        /// ``SBApplication/initWithProcessIdentifier:`` and
        /// ``SBApplication/initWithURL:``, this method is not dependent on changeable
        /// factors such as the target application's path or process ID. Even so, you
        /// should rarely have to initialize an `SBApplication` object yourself;
        /// instead, you should initialize an application-specific subclass such as
        /// `iTunesApplication`.
        ///
        /// Note that this method does not check whether an application with the given
        /// bundle identifier actually exists.
        ///
        /// - Parameters:
        /// - ident: A bundle identifier specifying an application that is
        /// OSA-compliant.
        ///
        /// - Returns: An initialized shared instance of an `SBApplication` subclass
        /// that represents a target application with the bundle identifier of `ident`.
        /// Returns `nil` if no such application can be found or if the application does
        /// not have a scripting interface.
        #[unsafe(method(initWithBundleIdentifier:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithBundleIdentifier(
            this: Allocated<Self>,
            ident: &NSString,
        ) -> Option<Retained<SBApplication>>;

        /// Returns an instance of an `SBApplication` subclass that represents the
        /// target application identified by the given URL.
        ///
        /// This approach to initializing `SBApplication` objects should be used only if
        /// you know for certain the URL of the target application. In most cases, it is
        /// better to use ``SBApplication/applicationWithBundleIdentifier:`` which
        /// dynamically locates the target application at runtime. Even so, you should
        /// rarely have to initialize an `SBApplication` yourself.
        ///
        /// This method currently supports file URLs (`file:`) and remote application
        /// URLs (`eppc:`). It checks whether a file exists at the specified path, but
        /// it does not check whether an application identified via `eppc:` exists.
        ///
        /// - Parameters:
        /// - url: A Universal Resource Locator (URL) specifying an application that is
        /// OSA-compliant.
        ///
        /// - Returns: An initialized `SBApplication` that you can use to communicate
        /// with the target application specified by the process ID. Returns `nil` if an
        /// application could not be found or if the application does not have a
        /// scripting interface.
        #[unsafe(method(initWithURL:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithURL(
            this: Allocated<Self>,
            url: &NSURL,
        ) -> Option<Retained<SBApplication>>;

        #[cfg(feature = "libc")]
        /// Returns an instance of an `SBApplication` subclass that represents the
        /// target application identified by the given process identifier.
        ///
        /// You should avoid using this method unless you know nothing about an external
        /// application but its PID. In most cases, it is better to use
        /// ``SBApplication/initWithBundleIdentifier:``, which will dynamically locate
        /// the external application's path at runtime, or
        /// ``SBApplication/initWithURL:``, which is not dependent on the external
        /// application being open at the time the method is called.
        ///
        /// - Parameters:
        /// - pid: A BSD process ID specifying an application that is OSA-compliant.
        /// Often you can get the process ID of a process using the
        /// <doc
        /// ://com.apple.documentation/documentation/foundation/nstask/1412022-processidentifier>
        /// method of `NSTask`.
        ///
        /// - Returns: An initialized `SBApplication` that you can use to communicate
        /// with the target application specified by the process ID. Returns `nil` if no
        /// such application can be found or if the application does not have a
        /// scripting interface.
        #[unsafe(method(initWithProcessIdentifier:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithProcessIdentifier(
            this: Allocated<Self>,
            pid: libc::pid_t,
        ) -> Option<Retained<SBApplication>>;

        /// Returns the shared instance representing the target application specified by
        /// its bundle identifier.
        ///
        /// For applications that declare themselves to have a dynamic scripting
        /// interface, this method will launch the application if it is not already
        /// running.
        ///
        /// - Parameters:
        /// - ident: A bundle identifier specifying an application that is OSA-compliant.
        ///
        /// - Returns: An instance of a `SBApplication` subclass that represents the
        /// target application whose bundle identifier is `ident`. Returns `nil` if no
        /// such application can be found or if the application does not have a
        /// scripting interface.
        #[unsafe(method(applicationWithBundleIdentifier:))]
        #[unsafe(method_family = none)]
        pub unsafe fn applicationWithBundleIdentifier(
            ident: &NSString,
        ) -> Option<Retained<SBApplication>>;

        /// Returns the shared instance representing a target application specified by
        /// the given URL.
        ///
        /// For applications that declare themselves to have a dynamic scripting
        /// interface, this method will launch the application if it is not already
        /// running. This approach to initializing `SBApplication` objects should be
        /// used only if you know for certain the URL of the target application. In most
        /// cases, it is better to use
        /// ``SBApplication/applicationWithBundleIdentifier:`` which dynamically locates
        /// the target application at runtime.
        ///
        /// This method currently supports file URLs (`file:`) and remote application
        /// URLs (`eppc:`). It checks whether a file exists at the specified path, but
        /// it does not check whether an application identified via `eppc:` exists.
        ///
        /// - Parameters:
        /// - url: The Universal Resource Locator (URL) locating an OSA-compliant
        /// application.
        ///
        /// - Returns: An `SBApplication` subclass from which to generate a shared
        /// instance of the target application whose URL is `url`. Returns `nil` if no
        /// such application can be found or if the application does not have a
        /// scripting interface.
        #[unsafe(method(applicationWithURL:))]
        #[unsafe(method_family = none)]
        pub unsafe fn applicationWithURL(url: &NSURL) -> Option<Retained<SBApplication>>;

        #[cfg(feature = "libc")]
        /// Returns the shared instance representing a target application specified by
        /// its process identifier.
        ///
        /// You should avoid using this method unless you know nothing about a target
        /// application but its process ID. In most cases, it is better to use
        /// ``SBApplication/applicationWithBundleIdentifier:``, which will dynamically
        /// locate the application's path at runtime, or
        /// ``SBApplication/applicationWithURL:``, which is not dependent on the target
        /// application being open at the time the method is called.
        ///
        /// - Parameters:
        /// - pid: The BSD process ID of a OSA-compliant application. Often you can get
        /// the process ID of a process using the
        /// <doc
        /// ://com.apple.documentation/documentation/foundation/nstask/1412022-processidentifier>
        /// method of `NSTask`.
        ///
        /// - Returns: An instance of an `SBApplication` subclass that represents the
        /// target application whose process identifier is `pid`. Returns `nil` if no
        /// such application can be found or if the application does not have a
        /// scripting interface.
        #[unsafe(method(applicationWithProcessIdentifier:))]
        #[unsafe(method_family = none)]
        pub unsafe fn applicationWithProcessIdentifier(
            pid: libc::pid_t,
        ) -> Option<Retained<SBApplication>>;

        /// Returns a class object that represents a particular class in the target
        /// application.
        ///
        /// You invoke this method on an instance of a scriptable application. Once you
        /// have the class object, you may allocate an instance of the class and
        /// appropriately the raw instance. Or you may use it in a call to
        /// <doc
        /// ://com.apple.documentation/documentation/objectivec/1418956-nsobject/1418511-iskindofclass>
        /// to determine the class type of an object.
        ///
        /// - Parameters:
        /// - className: The name of the scripting class, as it appears in the scripting interface. For example, "document".
        ///
        /// - Returns: A `Class` object representing the scripting class.
        #[unsafe(method(classForScriptingClass:))]
        #[unsafe(method_family = none)]
        pub unsafe fn classForScriptingClass(
            &self,
            class_name: &NSString,
        ) -> Option<&'static AnyClass>;

        /// A Boolean that indicates whether the target application represented by the
        /// receiver is running.
        ///
        /// <doc
        /// ://com.apple.documentation/documentation/swift/true> if the application
        /// is running,
        /// <doc
        /// ://com.apple.documentation/documentation/swift/false>
        /// otherwise.
        ///
        /// This may be
        /// <doc
        /// ://com.apple.documentation/documentation/swift/true> for instances initialized with a bundle identifier or URL because
        /// `SBApplication` launches the application only when it's necessary to send
        /// it an event.
        #[unsafe(method(isRunning))]
        #[unsafe(method_family = none)]
        pub unsafe fn isRunning(&self) -> bool;

        /// Moves the target application to the foreground immediately.
        ///
        /// If the target application is not already running, this method launches it.
        #[unsafe(method(activate))]
        #[unsafe(method_family = none)]
        pub unsafe fn activate(&self);

        /// The error-handling delegate of the receiver.
        ///
        /// The delegate should implement the
        /// ``SBApplicationDelegate/eventDidFail:withError:`` method of the
        /// ``SBApplicationDelegate`` informal protocol.
        #[unsafe(method(delegate))]
        #[unsafe(method_family = none)]
        pub unsafe fn delegate(
            &self,
        ) -> Option<Retained<ProtocolObject<dyn SBApplicationDelegate>>>;

        /// Setter for [`delegate`][Self::delegate].
        #[unsafe(method(setDelegate:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setDelegate(
            &self,
            delegate: Option<&ProtocolObject<dyn SBApplicationDelegate>>,
        );

        #[cfg(feature = "objc2-core-services")]
        /// The launch flags for the application represented by the receiver.
        ///
        /// For more information, see
        /// <doc
        /// ://com.apple.documentation/documentation/coreservices/launch_services>.
        #[unsafe(method(launchFlags))]
        #[unsafe(method_family = none)]
        pub unsafe fn launchFlags(&self) -> LSLaunchFlags;

        #[cfg(feature = "objc2-core-services")]
        /// Setter for [`launchFlags`][Self::launchFlags].
        #[unsafe(method(setLaunchFlags:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setLaunchFlags(&self, launch_flags: LSLaunchFlags);

        #[cfg(feature = "objc2-core-services")]
        /// The mode for sending Apple events to the target application.
        ///
        /// For more information, see
        /// <doc
        /// ://com.apple.documentation/documentation/applicationservices/apple_event_manager>.
        ///
        /// The default send mode is
        /// <doc
        /// ://com.apple.documentation/documentation/coreservices/1542914-anonymous/kaewaitreply>.
        /// If the send mode is something other than `kAEWaitReply`, the receiver might
        /// not correctly handle reply events from the target application.
        #[unsafe(method(sendMode))]
        #[unsafe(method_family = none)]
        pub unsafe fn sendMode(&self) -> AESendMode;

        #[cfg(feature = "objc2-core-services")]
        /// Setter for [`sendMode`][Self::sendMode].
        #[unsafe(method(setSendMode:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setSendMode(&self, send_mode: AESendMode);

        /// The period the application will wait to receive reply Apple events.
        ///
        /// For more information, see
        /// <doc
        /// ://com.apple.documentation/documentation/applicationservices/apple_event_manager>.
        ///
        /// The default timeout value is
        /// <doc
        /// ://com.apple.documentation/documentation/coreservices/1542814-timeout_constants/kaedefaulttimeout>,
        /// which is about a minute. If you want the receiver to wait indefinitely for
        /// reply Apple events, use
        /// <doc
        /// ://com.apple.documentation/documentation/coreservices/1542814-timeout_constants/knotimeout>.
        /// For more information, see
        /// <doc
        /// ://com.apple.documentation/documentation/applicationservices/apple_event_manager>.
        #[unsafe(method(timeout))]
        #[unsafe(method_family = none)]
        pub unsafe fn timeout(&self) -> c_long;

        /// Setter for [`timeout`][Self::timeout].
        #[unsafe(method(setTimeout:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setTimeout(&self, timeout: c_long);
    );
}

/// Methods declared on superclass `SBObject`.
#[cfg(feature = "SBObject")]
impl SBApplication {
    extern_methods!(
        /// Initializes and returns an instance of an `SBObject` subclass.
        ///
        /// Scripting Bridge does not actually create an object in the target
        /// application until you add the object returned from this method to an element
        /// array (``SBElementArray``).
        ///
        /// - Returns: An `SBObject` object or `nil` if the object could not be
        /// initialized.
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        /// Returns an instance of an `SBObject` subclass initialized with the specified
        /// properties.
        ///
        /// Scripting Bridge does not actually create an object in the target
        /// application until you add the object returned from this method to an element
        /// array (``SBElementArray``).
        ///
        /// - Parameters:
        /// - properties: A dictionary with keys specifying the names of properties
        /// (that is, attributes or to-one relationships) and the values for those
        /// properties.
        ///
        /// - Returns: An `SBObject` object or `nil` if the object could not be
        /// initialized.
        ///
        /// # Safety
        ///
        /// `properties` generic should be of the correct type.
        #[unsafe(method(initWithProperties:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithProperties(
            this: Allocated<Self>,
            properties: &NSDictionary,
        ) -> Retained<Self>;

        /// Returns an instance of an `SBObject` subclass initialized with the given
        /// data.
        ///
        /// Scripting Bridge does not actually create an object in the target
        /// application until you add the object returned from this method to an element
        /// array (``SBElementArray``).
        ///
        /// - Parameters:
        /// - data: An object containing data for the new `SBObject` object. The data
        /// varies according to the type of scripting object to be created.
        ///
        /// - Returns: An `SBObject` object or `nil` if the object could not be
        /// initialized.
        ///
        /// # Safety
        ///
        /// `data` should be of the correct type.
        #[unsafe(method(initWithData:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithData(this: Allocated<Self>, data: &AnyObject) -> Retained<Self>;
    );
}

/// Methods declared on superclass `NSObject`.
#[cfg(feature = "SBObject")]
impl SBApplication {
    extern_methods!(
        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}

extern_protocol!(
    /// This informal protocol defines a delegation method for handling Apple event
    /// errors that are sent from a target application to an
    /// <doc
    /// ://com.apple.documentation/documentation/scriptingbridge/sbapplication>
    /// object.
    ///
    /// You must set a delegate for the ``SBApplication`` object using the
    /// ``SBApplication/delegate`` method. If you do not set a delegate and have the
    /// delegate handle the error in some way, ``SBApplication`` raises an
    /// exception.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/scriptingbridge/sbapplicationdelegate?language=objc)
    pub unsafe trait SBApplicationDelegate {
        #[cfg(feature = "objc2-core-services")]
        /// Sent by an `SBApplication` object when a target application returns an error
        /// Apple event.
        ///
        /// - Parameters:
        /// - event: A pointer to the Apple event sent to the target application causing
        /// the error.
        ///
        /// - error: An object containing information about the error Apple event.
        /// Specific information may be included in the `useInfo` dictionary of the
        /// error object. The following table shows the possible
        /// keys for this dictionary.
        ///
        /// | Key | Description |
        /// | ----------- | --------------- |
        /// | ErrorBriefMessage | A short human-readable description of the error, as an
        /// <doc
        /// ://com.apple.documentation/documentation/foundation/nsstring> |
        /// | ErrorExpectedType | The type of data the target application expected, as an
        /// <doc
        /// ://com.apple.documentation/documentation/foundation/nsappleeventdescriptor> object. |
        /// | ErrorOffendingObject | The object that caused the error. |
        /// | ErrorString | A full human-readable description of the error, as an
        /// <doc
        /// ://com.apple.documentation/documentation/foundation/nsstring> object. |
        /// | ErrorNumber | The Apple event error number, as an
        /// <doc
        /// ://com.apple.documentation/documentation/foundation/nsnumber> object. |
        ///
        /// - Returns: If you return a result, it will become the result of the
        /// <doc
        /// ://com.apple.documentation/documentation/appkit/nsapplication/1428359-sendevent>
        /// that failed. Can be `nil`.
        ///
        /// # Safety
        ///
        /// `event` must be a valid pointer.
        #[unsafe(method(eventDidFail:withError:))]
        #[unsafe(method_family = none)]
        unsafe fn eventDidFail_withError(
            &self,
            event: NonNull<AppleEvent>,
            error: &NSError,
        ) -> Option<Retained<AnyObject>>;
    }
);