### Register Sample Launch Agent Source: https://developer.apple.com/documentation/servicemanagement/updating-your-app-package-installer-to-use-the-new-service-management-api Use this command to register the SampleLaunchAgent. Ensure the path to the executable is correct for your setup. ```bash % /Library/Application Support/YOURDEVELOPERNAME/SMAppServiceSampleCode.app/Contents/MacOS/SMAppServiceSampleCode register Successfully registered LaunchAgent(com.xpc.example.agent.plist) ``` -------------------------------- ### Enable a Login Item Source: https://developer.apple.com/documentation/servicemanagement Use this function to enable or disable a helper executable that is part of your app's main bundle. This is typically used for login items that start when the user logs in. ```c func SMLoginItemSetEnabled(_: CFString, _: Bool) -> Bool ``` -------------------------------- ### Get Main App Service Source: https://developer.apple.com/documentation/servicemanagement/smappservice/loginitem%28identifier%3A%29 Retrieves an app service object that represents the main application as a login item. ```swift class var mainApp: SMAppService ``` -------------------------------- ### kSMRightBlessPrivilegedHelper Source: https://developer.apple.com/documentation/servicemanagement/ksmrightmodifysystemdaemons The authorization rights key for approving and installing a privileged helper tool. Available on Mac Catalyst and macOS. ```APIDOC ## Constants ### kSMRightBlessPrivilegedHelper The authorization rights key for approving and installing a privileged helper tool. **Availability:** * Mac Catalyst * macOS ### Declaration ```swift var kSMRightBlessPrivilegedHelper: String { get } ``` ``` -------------------------------- ### kSMRightBlessPrivilegedHelper Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmrightblessprivilegedhelper The authorization rights key for approving and installing a privileged helper tool. Available on Mac Catalyst 13.0+ and macOS 10.6+. ```APIDOC ## Constant Declaration ### Description The authorization rights key for approving and installing a privileged helper tool. ### Availability Mac Catalyst 13.0+ macOS 10.6+ ### Code Example ```swift var kSMRightBlessPrivilegedHelper: String { get } ``` ``` -------------------------------- ### Getting Service Status Source: https://developer.apple.com/documentation/servicemanagement/smappservice Properties and enums for checking the status of a registered service. ```APIDOC ## Getting the state of the service `var status: SMAppService.Status` A property that describes registration or authorization state of the service. `enum Status` Constants that describe the registration or authorization status of a helper executable. ``` -------------------------------- ### Get SMAppService Status Source: https://developer.apple.com/documentation/servicemanagement/smappservice/status-swift.property Access the `status` property to determine the registration or authorization state of the service. This property is read-only. ```swift var status: SMAppService.Status { get } ``` -------------------------------- ### Declare kSMRightBlessPrivilegedHelper Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmrightblessprivilegedhelper This Swift code declares the authorization rights key for approving and installing a privileged helper tool. It is available on Mac Catalyst 13.0+ and macOS 10.6+. ```swift var kSMRightBlessPrivilegedHelper: String { get } ``` -------------------------------- ### Declare kSMRightBlessPrivilegedHelper Authorization Right Source: https://developer.apple.com/documentation/servicemanagement/ksmrightmodifysystemdaemons This constant represents the authorization rights key for approving and installing a privileged helper tool. It is available on macOS 10.6+ and Mac Catalyst 13.0+. ```swift var kSMRightBlessPrivilegedHelper: String ``` -------------------------------- ### SMAppServiceErrorDomain Source: https://developer.apple.com/documentation/servicemanagement/smappserviceerrordomain The SMAppServiceErrorDomain is a global variable used in Service Management. It is available on Mac Catalyst starting from version 18.0 and on macOS starting from version 15.0. ```APIDOC ## Global Variable ### SMAppServiceErrorDomain **Availability:** Mac Catalyst 18.0+, macOS 15.0+ ```swift let SMAppServiceErrorDomain: String ``` ``` -------------------------------- ### Initialize SMAppService helper references Source: https://developer.apple.com/documentation/servicemanagement/updating-helper-executables-from-earlier-versions-of-macos Create instances of SMAppService for different helper types using bundle identifiers or property list names. ```swift func initializer_demo() { // The identifier must match the CFBundleIdentifier string in Info.plist. // LoginItem path: $APP.app/Contents/Library/LoginItems/MyMenuExtra.app/Contents/Info.plist let loginItem = SMAppService.loginItem(identifier: "com.example.mymenuextra") // LaunchDaemon path: $APP.app/Contents/Library/LaunchDaemons/com.example.daemon.plist let daemon = SMAppService.daemon(plistName: "com.example.daemon.plist"); // LaunchAgent path: $APP.app/Contents/Library/LaunchAgents/com.example.agent.plist let agent = SMAppService.agent(plistName: "com.example.agent.plist"); // Retrieving the app reference if the main app itself needs to launch instead of a helper. let mainApp = SMAppService.mainApp } ``` -------------------------------- ### Test Sample Launch Agent Communication Source: https://developer.apple.com/documentation/servicemanagement/updating-your-app-package-installer-to-use-the-new-service-management-api Sends an XPC message to the SampleLaunchAgent and displays the reply. This is useful for verifying the agent is running and responsive. ```bash % /Library/Application Support/YOURDEVELOPERNAME/SMAppServiceSampleCode.app/Contents/MacOS/SMAppServiceSampleCode test Received "Hello World" ``` -------------------------------- ### class func agent(plistName: String) Source: https://developer.apple.com/documentation/servicemanagement/smappservice/agent%28plistname%3A%29 Initializes an app service object with a launch agent using the provided property list name. ```APIDOC ## class func agent(plistName: String) ### Description Initializes an app service object with a launch agent with the property list name you provide. The property list name must correspond to a property list in the calling app’s Contents/Library/LaunchAgents directory. ### Method Class Function ### Parameters #### Path Parameters - **plistName** (String) - Required - The name of the property list corresponding to the SMAppService. ### Availability - Mac Catalyst 16.0+ - macOS 13.0+ ``` -------------------------------- ### Register a Service with register() Source: https://developer.apple.com/documentation/servicemanagement/smappservice/register%28%29 Registers the service so it can begin launching subject to user approval. This method is available on Mac Catalyst 16.0+ and macOS 13.0+. ```swift func register() throws ``` -------------------------------- ### Check Sample Launch Agent Status Source: https://developer.apple.com/documentation/servicemanagement/updating-your-app-package-installer-to-use-the-new-service-management-api Use this command to check the current status of the SampleLaunchAgent. The rawValue indicates the service's state. ```bash % /Library/Application Support/YOURDEVELOPERNAME/SMAppServiceSampleCode.app/Contents/MacOS/SMAppServiceSampleCode status LaunchAgent(com.xpc.example.agent.plist) has status SMAppServiceStatus(rawValue: 1) ``` -------------------------------- ### Uninstall Sample Launch Agent Source: https://developer.apple.com/documentation/servicemanagement/updating-your-app-package-installer-to-use-the-new-service-management-api Removes the sample app's login item and the SampleLaunchAgent from the system. This command requires administrator privileges. ```bash sudo rm -rf /Library/Application Support/YOURDEVELOPERNAME ``` -------------------------------- ### openSystemSettingsLoginItems() Source: https://developer.apple.com/documentation/servicemanagement/smappservice/opensystemsettingsloginitems%28%29 Opens System Settings to the Login Items control panel. Available on Mac Catalyst 16.0+ and macOS 13.0+. ```APIDOC ## openSystemSettingsLoginItems() ### Description Opens System Settings to the Login Items control panel. ### Method Class Method ### Endpoint N/A (This is a function call, not a network endpoint) ### Parameters None ### Request Example ```swift SMAppService.openSystemSettingsLoginItems() ``` ### Response N/A (This method does not return a value, it performs an action.) ### Availability Mac Catalyst 16.0+ macOS 13.0+ ``` -------------------------------- ### Initialize SMAppService for Launch Agent Source: https://developer.apple.com/documentation/servicemanagement/smappservice/loginitem%28identifier%3A%29 Initializes an app service object for a launch agent using its property list name. ```swift class func agent(plistName: String) -> Self ``` -------------------------------- ### Initialize SMAppService for Login Item Source: https://developer.apple.com/documentation/servicemanagement/smappservice/loginitem%28identifier%3A%29 Use this method to create an `SMAppService` object for a login item. The provided identifier must match a property list in the calling app's `Contents/Library/LoginItems` directory. ```swift class func loginItem(identifier: String) -> Self ``` -------------------------------- ### Error Testing Sample Launch Agent Source: https://developer.apple.com/documentation/servicemanagement/updating-your-app-package-installer-to-use-the-new-service-management-api This error message appears when attempting to test the SampleLaunchAgent before it has been registered or after it has been unregistered. ```bash % /Library/Application Support/YOURDEVELOPERNAME/SMAppServiceSampleCode.app/Contents/MacOS/SMAppServiceSampleCode test Unable to create xpc_session ``` -------------------------------- ### SMLoginItemSetEnabled(_:_:) Source: https://developer.apple.com/documentation/servicemanagement/smloginitemsetenabled%28_%3A_%3A%29 Enables or disables a helper executable located in the main app-bundle directory. ```APIDOC ## SMLoginItemSetEnabled(_:_:) ### Description Enables a helper executable in the main app-bundle directory. Note that this function is deprecated in macOS 13 and later; use register() and unregister() instead. ### Method Function Call ### Parameters - **identifier** (CFString) - Required - The identifier of the helper executable bundle. - **enabled** (Bool) - Required - A Boolean value that represents the state of the helper executable. If true, the helper tool runs immediately and upon subsequent logins. If false, the helper executable stops. ### Return Value - **Bool** - Returns true if the requested change has taken effect. ### Request Example SMLoginItemSetEnabled("com.example.helper" as CFString, true) ### Response - **Bool** - true or false ``` -------------------------------- ### Interacting with System Settings Source: https://developer.apple.com/documentation/servicemanagement/smappservice Opens System Settings to the Login Items control panel. ```APIDOC ## Interacting with System Settings `class func openSystemSettingsLoginItems()` Opens System Settings to the Login Items control panel. ``` -------------------------------- ### Register a launch agent Source: https://developer.apple.com/documentation/servicemanagement/updating-your-app-package-installer-to-use-the-new-service-management-api Initializes an agent object using a plist name and registers it with the system. ```swift let service = SMAppService.agent(plistName: "com.xpc.example.agent.plist") do { try service.register() print("Successfully registered \(service)") } catch { print("Unable to register \(error)") exit(1) } ``` -------------------------------- ### Unregister Sample Launch Agent Source: https://developer.apple.com/documentation/servicemanagement/updating-your-app-package-installer-to-use-the-new-service-management-api Use this command to unregister the SampleLaunchAgent. This should be done before uninstalling the agent. ```bash % /Library/Application Support/YOURDEVELOPERNAME/SMAppServiceSampleCode.app/Contents/MacOS/SMAppServiceSampleCode unregister Successfully unregistered LaunchAgent(com.xpc.example.agent.plist) ``` -------------------------------- ### SMLoginItemSetEnabled Function Source: https://developer.apple.com/documentation/servicemanagement Enables a helper executable in the main app-bundle directory. ```APIDOC ## func SMLoginItemSetEnabled(CFString, Bool) -> Bool ### Description Enables a helper executable in the main app-bundle directory. ### Status Deprecated ``` -------------------------------- ### SMAppService.register() Source: https://developer.apple.com/documentation/servicemanagement/smappservice/register%28%29 Registers the service so it can begin launching subject to user approval. This method is available on macOS 13.0+ and Mac Catalyst 16.0+. ```APIDOC ## POST /register ### Description Registers the service so it can begin launching subject to user approval. ### Method POST ### Endpoint /register ### Parameters This method does not take any parameters. ### Request Body This method does not have a request body. ### Response #### Success Response (200) Indicates successful registration. #### Error Response - **kSMErrorAlreadyRegistered** - If the service is already registered. - **kSMErrorLaunchDeniedByUser** - If the service isn’t approved by the user. ### Request Example ```swift // No direct HTTP request example, this is a Swift method call // SMAppService.register() ``` ### Response Example ```json // Success: No specific JSON response, method returns void on success. // Errors are returned as thrown exceptions or specific error codes. ``` ``` -------------------------------- ### kSMDomainUserLaunchd Source: https://developer.apple.com/documentation/servicemanagement/ksmdomainuserlaunchd The user-level launch domain. Available on iOS 3.0+, iPadOS 3.0+, macOS 10.6+, and Mac Catalyst 13.1+. ```APIDOC ## Constant Declaration ### Description The user-level launch domain. ### Availability iOS 3.0+iPadOS 3.0+Mac Catalyst 13.1+macOS 10.6+ ### Code Example ```swift let kSMDomainUserLaunchd: CFString! ``` ``` -------------------------------- ### POST SMJobBless Source: https://developer.apple.com/documentation/servicemanagement/property-list-keys Submits an executable for a given label as a job to launchd. ```APIDOC ## SMJobBless ### Description Submits the executable for the given label as a job to launchd. Note: This function is deprecated. ### Method Function Call ### Parameters - **label** (CFString!) - Required - The label of the executable. - **executableLabel** (CFString) - Required - The label of the executable to submit. - **authRef** (AuthorizationRef!) - Required - The authorization reference. - **error** (UnsafeMutablePointer?>!) - Required - Pointer to an error object. ### Response - **Returns** (Bool) - Returns true if the job was successfully submitted, false otherwise. ``` -------------------------------- ### kSMDomainSystemLaunchd Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmdomainsystemlaunchd The kSMDomainSystemLaunchd constant represents the system-level launch domain. It is available on iOS, iPadOS, Mac Catalyst, and macOS. ```APIDOC ## Constant Declaration: kSMDomainSystemLaunchd ### Description The system-level launch domain. ### Availability iOS 3.0+ iPadOS 3.0+ Mac Catalyst 13.1+ macOS 10.6+ ### Declaration ```swift let kSMDomainSystemLaunchd: CFString! ``` ### See Also - `kSMDomainUserLaunchd`: The user-level launch domain. ``` -------------------------------- ### Register and unregister helper executables Source: https://developer.apple.com/documentation/servicemanagement/updating-helper-executables-from-earlier-versions-of-macos Handle user interaction to register or unregister a service, including error handling for registration and completion handlers for unregistration. ```swift func handle_checkbox_toggle(_ checked: Bool) { let service = SMAppService.loginItem(identifier:"com.example.mymenuextra") if (checked) { do { try service.register() } catch { os_log("Unable to register \(error)") } } else { service.unregister(completionHandler: { error in if let error = error { os_log("Unable to unregister \(error)") } else { // Successfully unregistered service. } }) } } ``` -------------------------------- ### SMAppService - daemon(plistName:) Source: https://developer.apple.com/documentation/servicemanagement/smappservice/daemon%28plistname%3A%29 Initializes an app service object with a launch daemon using the provided property list name. This method is available on Mac Catalyst 16.0+ and macOS 13.0+. ```APIDOC ## POST /daemon ### Description Initializes an app service object with a launch daemon with the property list name you provide. ### Method POST ### Endpoint /daemon ### Parameters #### Query Parameters - **plistName** (String) - Required - The name of the property list corresponding to the SMAppService. ### Request Body ```json { "plistName": "your_daemon_plist_name" } ``` ### Response #### Success Response (200) - **SMAppService** (Object) - An SMAppService object representing the initialized app service. #### Response Example ```json { "serviceType": "daemon", "plistName": "your_daemon_plist_name" } ``` ### Discussion The property list name must correspond to a property list in the calling app’s `Contents/Library/LaunchDaemons` directory. ### See Also - `class var mainApp: SMAppService` - `class func agent(plistName: String) -> Self` - `class func loginItem(identifier: String) -> Self` ``` -------------------------------- ### kSMDomainSystemLaunchd Source: https://developer.apple.com/documentation/servicemanagement/ksmdomainuserlaunchd The system-level launch domain. This constant is related to kSMDomainUserLaunchd. ```APIDOC ## Constant Declaration ### Description The system-level launch domain. ### Related Constants `kSMDomainUserLaunchd` ### Code Example ```swift let kSMDomainSystemLaunchd: CFString! ``` ``` -------------------------------- ### Open System Settings Login Items Source: https://developer.apple.com/documentation/servicemanagement/smappservice/opensystemsettingsloginitems%28%29 Call this method to navigate the user directly to the Login Items section within System Settings. Requires macOS 13.0+ or Mac Catalyst 16.0+. ```swift class func openSystemSettingsLoginItems() ``` -------------------------------- ### class func statusForLegacyPlist(at:) Source: https://developer.apple.com/documentation/servicemanagement/smappservice/statusforlegacyplist%28at%3A%29 Checks the authorization status of an earlier OS version login item. ```APIDOC ## class func statusForLegacyPlist(at:) ### Description Check the authorization status of an earlier OS version login item. ### Method Class Method ### Parameters #### Path Parameters - **url** (URL) - Required - The URL of the helper executable’s property list. ### Response - **Return Value** (SMAppService.Status) - One of the SMAppService.Status constants that indicate the current authorization status. ``` -------------------------------- ### User-Level Launch Domain Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmdomainsystemlaunchd This constant represents the user-level launch domain. It is provided as a related constant for comparison. ```swift let kSMDomainUserLaunchd: CFString! ``` -------------------------------- ### Initialize a launch daemon app service Source: https://developer.apple.com/documentation/servicemanagement/smappservice/daemon%28plistname%3A%29 Initializes an app service object with a launch daemon using the provided property list name. The plist must exist in the app's Contents/Library/LaunchDaemons directory. ```swift class func daemon(plistName: String) -> Self ``` -------------------------------- ### Define SMAppService class Source: https://developer.apple.com/documentation/servicemanagement/smappservice The base class definition for managing helper executables. ```swift class SMAppService ``` -------------------------------- ### SMCopyAllJobDictionaries(_:) Source: https://developer.apple.com/documentation/servicemanagement/smjobcopydictionary%28_%3A_%3A%29 Copies the job description dictionaries for all jobs in the specified domain. ```APIDOC ## SMCopyAllJobDictionaries(_:) ### Description Copies the job description dictionaries for all jobs in the specified domain. ### Parameters - **domain** (CFString!) - Required - The job’s domain. ``` -------------------------------- ### SMAppService Initializer Source: https://developer.apple.com/documentation/servicemanagement/smappservice/status-swift.enum/init%28rawvalue%3A%29 Initializes a new instance of SMAppService with a raw integer value. Available on macOS 10.6+ and Mac Catalyst 13.0+. ```APIDOC ## Initializer: init(rawValue:) ### Description Initializes a new instance of `SMAppService` with a raw integer value. ### Method `init?(rawValue: Int)` ### Availability macOS 10.6+ Mac Catalyst 13.0+ ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response (200) None #### Response Example None ``` -------------------------------- ### SMAppService loginItem(identifier:) Source: https://developer.apple.com/documentation/servicemanagement/smappservice/loginitem%28identifier%3A%29 Initializes an app service object for a login item corresponding to the bundle with the identifier you provide. Available on Mac Catalyst 16.0+ and macOS 13.0+. ```APIDOC ## SMAppService loginItem(identifier:) ### Description Initializes an app service object for a login item corresponding to the bundle with the identifier you provide. ### Method `class func loginItem(identifier: String) -> Self` ### Endpoint N/A (This is a class method, not a network endpoint) ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```swift let service = SMAppService.loginItem(identifier: "com.example.LoginHelperApp") ``` ### Response #### Success Response (200) - **SMAppService** (Self) - An `SMAppService` object representing the login item. #### Response Example ```swift // Assuming the service object is successfully created // let service: SMAppService = ... ``` ### Discussion The property list name must correspond to a property list in the calling app’s `Contents/Library/LoginItems` directory. ### See Also - `class var mainApp: SMAppService` - `class func agent(plistName: String) -> Self` - `class func daemon(plistName: String) -> Self` ``` -------------------------------- ### SMAppService Class Overview Source: https://developer.apple.com/documentation/servicemanagement/smappservice The SMAppService class is used to control helper executables that reside within an app's main bundle. It provides methods for registering and unregistering services such as LoginItems, LaunchAgents, and LaunchDaemons. ```APIDOC ## SMAppService An object the framework uses to control helper executables that live inside an app’s main bundle. Mac Catalyst 16.0+ macOS 13.0+ ### Overview In macOS 13 and later, use `SMAppService` to register and control `LoginItems`, `LaunchAgents`, and `LaunchDaemons` as helper executables for your app. When converting code from earlier versions of macOS, use an `SMAppService` object and select one of the following methods depending on the type of service your helper executable provides: * For `SMAppServices` initialized as `LoginItems`, the `register()` and `unregister()` APIs provide a replacement for `SMLoginItemSetEnabled(_:_:)`. * For `SMAppServices` initialized as `LaunchAgents`, the `register()` and `unregister()` methods provide a replacement for installing property lists in `~/Library/LaunchAgents` or `/Library/LaunchAgents`. * For `SMAppServices` initialized as `LaunchDaemons`, the `register()` and `unregister()` methods provide a replacement for installing property lists in `/Library/LaunchDaemons`. ``` -------------------------------- ### SMAppService.mainApp Property Source: https://developer.apple.com/documentation/servicemanagement/smappservice/mainapp Retrieves the app service object corresponding to the main application as a login item. ```APIDOC ## GET SMAppService.mainApp ### Description An app service object that corresponds to the main application as a login item. Use this to configure the main app to launch at login. ### Availability - Mac Catalyst 16.0+ - macOS 13.0+ ### Declaration class var mainApp: SMAppService { get } ``` -------------------------------- ### Management Functions and Classes Source: https://developer.apple.com/documentation/servicemanagement/authorization-constants Core classes and functions for managing helper executables and daemon jobs. ```APIDOC ## Management API ### SMAppService - **Description**: An object the framework uses to control helper executables that live inside an app’s main bundle. ### SMJobBless - **Description**: Submits the executable for the given label as a job to launchd. - **Status**: Deprecated - **Parameters**: - **label** (CFString!) - **authorization** (AuthorizationRef!) - **error** (UnsafeMutablePointer?>!) - **Returns**: Bool ``` -------------------------------- ### System-Level Launch Domain Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmdomainsystemlaunchd Use this constant to refer to the system-level launch domain. Available on iOS 3.0+, iPadOS 3.0+, macOS 10.6+, and Mac Catalyst 13.1+. ```swift let kSMDomainSystemLaunchd: CFString! ``` -------------------------------- ### Service Management Constants Source: https://developer.apple.com/documentation/servicemanagement/property-list-keys Constants defining the launch domains for system and user-level services. ```APIDOC ## Constants ### kSMDomainSystemLaunchd - **Type**: CFString! - **Description**: The system-level launch domain. ### kSMDomainUserLaunchd - **Type**: CFString! - **Description**: The user-level launch domain. ``` -------------------------------- ### Submit a Job to launchd Source: https://developer.apple.com/documentation/servicemanagement This function submits an executable as a job to `launchd`, which manages system-level processes. It is used to register helper executables that should be managed by the system's launch daemon. ```c func SMJobBless(CFString!, CFString, AuthorizationRef!, UnsafeMutablePointer?>!) -> Bool ``` -------------------------------- ### SMAppService.Status.enabled Constant Source: https://developer.apple.com/documentation/servicemanagement/smappservice/status-swift.enum/notfound Signifies that the service has been successfully registered and is ready to be run. ```swift case enabled ``` -------------------------------- ### SMJobBless Function Source: https://developer.apple.com/documentation/servicemanagement Submits an executable for a given label as a job to launchd. ```APIDOC ## func SMJobBless(CFString!, CFString, AuthorizationRef!, UnsafeMutablePointer?>!) -> Bool ### Description Submits the executable for the given label as a job to launchd. ### Status Deprecated ``` -------------------------------- ### kSMErrorLaunchDeniedByUser Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmerrorinvalidplist Indicates that the user denied the app's launch request. Part of the Service Management framework. ```swift var kSMErrorLaunchDeniedByUser: Int ``` -------------------------------- ### SMAppService.Status.requiresApproval Constant Source: https://developer.apple.com/documentation/servicemanagement/smappservice/status-swift.enum/notfound Indicates that the service is registered but requires user interaction in System Preferences to proceed. ```swift case requiresApproval ``` -------------------------------- ### Accessing the mainApp property Source: https://developer.apple.com/documentation/servicemanagement/smappservice/mainapp Retrieves the SMAppService object for the main application to manage its login item status. ```swift class var mainApp: SMAppService { get } ``` -------------------------------- ### Initialize SMAppService.Status with rawValue Source: https://developer.apple.com/documentation/servicemanagement/smappservice/status-swift.enum/init%28rawvalue%3A%29 Creates a status instance from an integer raw value. Returns nil if the value does not correspond to a valid status. ```swift init?(rawValue: Int) ``` -------------------------------- ### SMAppService.status Property Source: https://developer.apple.com/documentation/servicemanagement/smappservice/status-swift.property Describes the registration or authorization state of a service. ```APIDOC ## Property: status ### Description A property that describes the registration or authorization state of the service. ### Availability - Mac Catalyst 16.0+ - macOS 13.0+ ### Declaration ```swift var status: SMAppService.Status { get } ``` ### See Also - enum Status: Constants that describe the registration or authorization status of a helper executable. ``` -------------------------------- ### Managing App Services Source: https://developer.apple.com/documentation/servicemanagement/smappservice APIs for creating and accessing SMAppService objects representing different types of app services. ```APIDOC ## Managing apps `class var mainApp: SMAppService` An app service object that corresponds to the main application as a login item. `class func agent(plistName: String) -> Self` Initializes an app service object with a launch agent with the property list name you provide. `class func daemon(plistName: String) -> Self` Initializes an app service object with a launch daemon with the property list name you provide. `class func loginItem(identifier: String) -> Self` Initializes an app service object for a login item corresponding to the bundle with the identifier you provide. ``` -------------------------------- ### Submit a job using SMJobSubmit Source: https://developer.apple.com/documentation/servicemanagement/smjobsubmit%28_%3A_%3A_%3A_%3A%29 Submits a job to a specified domain. Requires an authorization reference when targeting system launchd. ```Swift func SMJobSubmit( _ domain: CFString!, _ job: CFDictionary, _ auth: UnsafeMutableRawPointer!, _ outError: UnsafeMutablePointer?>! ) -> Bool ``` ```Swift func SMJobSubmit( _ domain: CFString!, _ job: CFDictionary, _ auth: AuthorizationRef!, _ outError: UnsafeMutablePointer?>! ) -> Bool ``` -------------------------------- ### Registering and Unregistering Services Source: https://developer.apple.com/documentation/servicemanagement/smappservice Methods for registering and unregistering helper services managed by SMAppService. ```APIDOC ## Registering services `func register() throws` Registers the service so it can begin launching subject to user approval. `func unregister() throws` Unregisters the service so the system no longer launches it. `func unregister(completionHandler: ((any Error)?) -> Void)` Unregisters the service so the system no longer launches it and calls a completion handler you provide with the resulting error value. ``` -------------------------------- ### SMAppService Class Source: https://developer.apple.com/documentation/servicemanagement An object used to control helper executables that reside inside an application's main bundle. ```APIDOC ## class SMAppService ### Description An object the framework uses to control helper executables that live inside an app’s main bundle. ``` -------------------------------- ### SMAppService.Status.notRegistered Case Source: https://developer.apple.com/documentation/servicemanagement/smappservice/status-swift.enum/notregistered Details the SMAppService.Status.notRegistered case, its conditions, and availability. ```APIDOC ## SMAppService.Status.notRegistered ### Description The service hasn’t registered with the Service Management framework, or the service attempted to reregister after it was already registered. ### Availability Mac Catalyst 13.0+ macOS 10.6+ ### Code Example ```swift case notRegistered ``` ### See Also #### Constants - `case enabled`: The service has been successfully registered and is eligible to run. - `case requiresApproval`: The service has been successfully registered, but the user needs to take action in System Preferences. - `case notFound`: An error occurred and the framework couldn’t find this service. ``` -------------------------------- ### SMCopyAllJobDictionaries(_:) Source: https://developer.apple.com/documentation/servicemanagement/smcopyalljobdictionaries%28_%3A%29 Copies the job description dictionaries for all jobs in the specified domain. This function is deprecated. ```APIDOC ## SMCopyAllJobDictionaries(_:) ### Description Copies the job description dictionaries for all jobs in the specified domain. ### Method Not applicable (this is a C-based function wrapper). ### Endpoint Not applicable. ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```swift // Swift example (conceptual, as this is a C API) let domain: CFString = kSMDomainSystemLaunchd let unmanagedArray: Unmanaged = SMCopyAllJobDictionaries_(domain) // Remember to release the array: unmanagedArray.release() ``` ### Response #### Success Response (200) - **CFArray** (Unmanaged) - A new array containing all job dictionaries. #### Response Example ```json // Conceptual representation of the returned CFArray content [ { "JobLabel": "com.example.myservice", "ProgramArguments": ["/usr/bin/mydaemon"] }, // ... other job dictionaries ] ``` ### Deprecated This function is deprecated and should not be used in new development. It is available in iOS 3.0–8.0, iPadOS 3.0–8.0, and macOS 10.6–10.10. ``` -------------------------------- ### SMCopyAllJobDictionaries Function Signature Source: https://developer.apple.com/documentation/servicemanagement/smcopyalljobdictionaries%28_%3A%29 Retrieves job description dictionaries for all jobs in a specified domain. The caller is responsible for releasing the returned array. ```swift func SMCopyAllJobDictionaries(_ domain: CFString!) -> Unmanaged! ``` -------------------------------- ### kSMErrorDomainLaunchd Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmerrordomainlaunchd The kSMErrorDomainLaunchd constant represents a Service Management error domain specifically for launchd-related issues. This constant is deprecated and should not be used in new development. ```APIDOC ## Global Variable # kSMErrorDomainLaunchd A Service Management `launchd` error domain. **Availability:** * iOS 3.0–8.0 (Deprecated) * iPadOS 3.0–8.0 (Deprecated) * Mac Catalyst 13.1–13.1 (Deprecated) * macOS 10.6–10.10 (Deprecated) ```swift let kSMErrorDomainLaunchd: CFString! ``` ### See Also #### Deprecated Constants * `let kSMErrorDomainFramework: CFString!` A Service Management error domain. Deprecated * `let kSMErrorDomainIPC: CFString!` A Service Management IPC error domain. Deprecated ``` -------------------------------- ### Unregister a launch agent Source: https://developer.apple.com/documentation/servicemanagement/updating-your-app-package-installer-to-use-the-new-service-management-api Initializes an agent object and removes the registration from the system. ```swift let service = SMAppService.agent(plistName: "com.xpc.example.agent.plist") do { try service.unregister() print("Successfully unregistered \(service)") } catch { print("Unable to unregister \(error)") exit(1) } ``` -------------------------------- ### SMAppService.Status.notRegistered Constant Source: https://developer.apple.com/documentation/servicemanagement/smappservice/status-swift.enum/notfound Indicates that the service has not yet registered with the Service Management framework, or it attempted to re-register after a previous registration. ```swift case notRegistered ``` -------------------------------- ### SMAppService.Status Constants Source: https://developer.apple.com/documentation/servicemanagement/smappservice/status-swift.enum/requiresapproval Enumeration of possible registration and execution statuses for a service managed by the Service Management framework. ```APIDOC ## SMAppService.Status Constants ### Description Defines the current registration and approval status of a service managed by the Service Management framework. ### Constants - **requiresApproval** - The service is registered, but requires user action in System Settings to run or consent has been revoked. - **notRegistered** - The service is not registered or an attempt was made to reregister an existing service. - **enabled** - The service is successfully registered and eligible to run. - **notFound** - The framework could not locate the specified service. ``` -------------------------------- ### SMAppService.Status.notFound Source: https://developer.apple.com/documentation/servicemanagement/smappservice/status-swift.enum/notfound Represents an error state where the framework is unable to locate the specified service. ```APIDOC ## SMAppService.Status.notFound ### Description An error occurred and the framework couldn’t find this service. ### Availability - Mac Catalyst 13.0+ - macOS 10.6+ ### Definition ```swift case notFound ``` ### Related Constants - **notRegistered**: The service hasn’t registered with the Service Management framework, or the service attempted to reregister after it was already registered. - **enabled**: The service has been successfully registered and is eligible to run. - **requiresApproval**: The service has been successfully registered, but the user needs to take action in System Preferences. ``` -------------------------------- ### kSMErrorAuthorizationFailure Source: https://developer.apple.com/documentation/servicemanagement/ksmerrorauthorizationfailure The authorization requested failed. This error occurs when a request requires specific authorization rights (e.g., adding a job to kSMDomainSystemLaunchd), but the provided AuthorizationRef does not possess the necessary rights. ```APIDOC ## kSMErrorAuthorizationFailure ### Description The authorization requested failed. ### Availability Mac Catalyst 13.0+ macOS 10.6+ ### Declaration ```swift var kSMErrorAuthorizationFailure: Int { get } ``` ### Discussion The request requires authorization (such as, adding a job to the `kSMDomainSystemLaunchd`), but the `AuthorizationRef` doesn’t contain the required right. ### See Also #### Constants - `var kSMErrorAlreadyRegistered: Int` - `var kSMErrorInternalFailure: Int` - `var kSMErrorInvalidPlist: Int` - `var kSMErrorInvalidSignature: Int` - `var kSMErrorJobMustBeEnabled: Int` - `var kSMErrorJobNotFound: Int` - `var kSMErrorJobPlistNotFound: Int` - `var kSMErrorLaunchDeniedByUser: Int` - `var kSMErrorServiceUnavailable: Int` - `var kSMErrorToolNotValid: Int` ``` -------------------------------- ### kSMErrorJobPlistNotFound Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmerrorinvalidplist Indicates that the job's property list was not found. Part of the Service Management framework. ```swift var kSMErrorJobPlistNotFound: Int ``` -------------------------------- ### Authorization Constants Source: https://developer.apple.com/documentation/servicemanagement/authorization-constants Constants defining authorization rights for system-level modifications. ```APIDOC ## Authorization Constants ### Description Constants that describe the ability to authorize helper executables or modify daemon applications. ### Constants - **kSMRightBlessPrivilegedHelper** (String) - The authorization rights key for approving and installing a privileged helper tool. - **kSMRightModifySystemDaemons** (String) - The authorization rights key for modifying system daemons. ``` -------------------------------- ### Reset Login Items Source: https://developer.apple.com/documentation/servicemanagement/updating-your-app-package-installer-to-use-the-new-service-management-api Resets all third-party login items to their default state. This command requires administrator privileges. ```bash sudo sfltool resetbtm ``` -------------------------------- ### Declare kSMErrorDomainLaunchd Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmerrordomainipc This constant represents a Service Management error domain specific to launchd. It is deprecated. ```swift let kSMErrorDomainLaunchd: CFString! ``` -------------------------------- ### SMJobCopyDictionary(_:_:) Source: https://developer.apple.com/documentation/servicemanagement/smjobcopydictionary%28_%3A_%3A%29 Copies the job description dictionary for the specified job label. ```APIDOC ## SMJobCopyDictionary(_:_:) ### Description Copies the job description dictionary for the specified job label. ### Parameters - **domain** (CFString!) - Required - The job’s domain (for example, kSMDomainSystemLaunchd). - **jobLabel** (CFString) - Required - The label identifier of the job to copy. ### Return Value A new dictionary describing the job, or NULL if the system couldn’t find the job. The caller must release the dictionary. ``` -------------------------------- ### kSMErrorDomainFramework Source: https://developer.apple.com/documentation/servicemanagement/ksmerrordomainframework A Service Management error domain constant. ```APIDOC ## kSMErrorDomainFramework ### Description A Service Management error domain. ### Declaration `let kSMErrorDomainFramework: CFString!` ### Availability - iOS 3.0–8.0 (Deprecated) - iPadOS 3.0–8.0 (Deprecated) - Mac Catalyst 13.1–13.1 (Deprecated) - macOS 10.6–10.10 (Deprecated) ``` -------------------------------- ### Related Constants Source: https://developer.apple.com/documentation/servicemanagement/ksmrightblessprivilegedhelper See also other related authorization rights keys. ```APIDOC ### Constants `var kSMRightModifySystemDaemons: String` The authorization rights key for modifying system daemons. `var kSMRightModifySystemDaemons: String` The authorization rights key for modifying system daemons. ``` -------------------------------- ### Check launch agent status Source: https://developer.apple.com/documentation/servicemanagement/updating-your-app-package-installer-to-use-the-new-service-management-api Retrieves the current authorization state of the specified launch agent. ```swift let service = SMAppService.agent(plistName: "com.xpc.example.agent.plist") print("\(service) has status \(service.status)") ``` -------------------------------- ### SMAppService.Status.notFound Case Source: https://developer.apple.com/documentation/servicemanagement/smappservice/status-swift.enum/notfound Represents the error case where the Service Management framework could not find the service. Available on Mac Catalyst 13.0+ and macOS 10.6+. ```swift case notFound ``` -------------------------------- ### SMJobBless Function Source: https://developer.apple.com/documentation/servicemanagement/smjobbless%28_%3A_%3A_%3A_%3A%29 Submits an executable for the given label as a job to launchd. This function is deprecated in macOS 13.0. ```APIDOC ## SMJobBless(_:_:_:_:) Deprecated ### Description Submits the executable for the given label as a job to `launchd`. ### Method (Implicitly a function call, not a typical HTTP method) ### Endpoint (Not applicable, this is a function call) ### Parameters #### Path Parameters (Not applicable) #### Query Parameters (Not applicable) #### Request Body (Not applicable) ### Request Example ```swift func SMJobBless( _ domain: CFString!, _ executableLabel: CFString, _ auth: AuthorizationRef!, _ outError: UnsafeMutablePointer?>! ) -> Bool ``` ### Response #### Success Response (true) Returns `true` if the job was successfully submitted. #### Error Response (false) Returns `false` if the job submission failed. #### Response Example ```swift true ``` ### Discussion `SMJobBless` submits the executable for the given label as a `launchd` job. This function removes the need for a `setuid(_:)` helper invoked through `AuthorizationExecuteWithPrivileges` in order to install a `launchd` property list. If the job is already installed, this methods returns `true`. **Requirements for using this function:** 1. Xcode must sign both the calling app and target executable tool. 2. The calling app’s `Info.plist` must include an `SMPrivilegedExecutables` dictionary of strings. Each string is a textual representation of a code signing requirement the system uses to determine whether the app owns the privileged tool once installed. 3. The helper tool must have an embedded `Info.plist` containing an `SMAuthorizedClients` array of strings. Each string is a textual representation of a code signing requirement describing a client allowed to add and remove the tool. 4. The helper tool must have an embedded launchd property list. The only required key in this property list is the `Label` key. You can’t specify your own program arguments; pass parameters through an inter-process communication (IPC) channel. 5. The helper tool must reside in the `Contents/Library/LaunchServices` directory inside the application bundle, and its name must be its launchd job label. ``` -------------------------------- ### kSMErrorJobNotFound Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmerrorinvalidplist Indicates that the system cannot find the specified job. Part of the Service Management framework. ```swift var kSMErrorJobNotFound: Int ``` -------------------------------- ### kSMErrorAlreadyRegistered Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmerrorinvalidplist Indicates that the application is already registered. Part of the Service Management framework. ```swift var kSMErrorAlreadyRegistered: Int ``` -------------------------------- ### Checking Authorization for Legacy Login Items Source: https://developer.apple.com/documentation/servicemanagement/smappservice Checks the authorization status of a legacy login item. ```APIDOC ## Checking authorization for earlier OS version login items `class func statusForLegacyPlist(at: URL) -> SMAppService.Status` Check the authorization status of an earlier OS version login item. ``` -------------------------------- ### kSMErrorToolNotValid Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmerrorinvalidplist Indicates that the specified path does not exist or the helper tool at the path is invalid. Part of the Service Management framework. ```swift var kSMErrorToolNotValid: Int ``` -------------------------------- ### kSMErrorAlreadyRegistered Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmerroralreadyregistered Indicates that the application is already registered. Available on Mac Catalyst 13.0+ and macOS 10.6+. ```swift var kSMErrorAlreadyRegistered: Int { get } ``` -------------------------------- ### SMLoginItemSetEnabled Function Signature Source: https://developer.apple.com/documentation/servicemanagement/smloginitemsetenabled%28_%3A_%3A%29 The function signature for enabling or disabling a helper executable. This function is deprecated as of macOS 13.0. ```swift func SMLoginItemSetEnabled( _ identifier: CFString, _ enabled: Bool ) -> Bool ``` -------------------------------- ### Other Service Management Constants Source: https://developer.apple.com/documentation/servicemanagement/ksmerrorinvalidplist A list of other relevant constants within the Service Management framework. ```APIDOC ### Constants `var kSMErrorAlreadyRegistered: Int` The application is already registered. `var kSMErrorAuthorizationFailure: Int` The authorization requested failed. `var kSMErrorInternalFailure: Int` An internal failure has occurred. `var kSMErrorInvalidSignature: Int` The app’s code signature doesn’t meet the requirements to perform the operation. `var kSMErrorJobMustBeEnabled: Int` `var kSMErrorJobNotFound: Int` The system can’t find the specified job. `var kSMErrorJobPlistNotFound: Int` `var kSMErrorLaunchDeniedByUser: Int` The user denied the app’s launch request. `var kSMErrorServiceUnavailable: Int` The service necessary to perform this operation is unavailable or is no longer accepting requests. `var kSMErrorToolNotValid: Int` The specified path doesn’t exist or the helper tool at the specified path isn’t valid. ``` -------------------------------- ### kSMErrorJobMustBeEnabled Constant Source: https://developer.apple.com/documentation/servicemanagement/ksmerrorinvalidplist Indicates that the job must be enabled. Part of the Service Management framework. ```swift var kSMErrorJobMustBeEnabled: Int ``` -------------------------------- ### Unregister Service with Completion Handler Source: https://developer.apple.com/documentation/servicemanagement/smappservice/unregister%28completionhandler%3A%29 Use this method to unregister a service, preventing the system from launching it. The completion handler is called with an error if the operation fails. ```swift func unregister(completionHandler handler: @escaping @Sendable ((any Error)?) -> Void) ``` -------------------------------- ### kSMErrorJobNotFound Source: https://developer.apple.com/documentation/servicemanagement/ksmerrorjobnotfound Represents an error where the system cannot find the specified job. ```APIDOC ## kSMErrorJobNotFound ### Description The system can’t find the specified job. ### Availability - Mac Catalyst 13.0+ - macOS 10.6+ ### Definition `var kSMErrorJobNotFound: Int { get }` ``` -------------------------------- ### Copy All Job Dictionaries - Swift Source: https://developer.apple.com/documentation/servicemanagement/smjobcopydictionary%28_%3A_%3A%29 Copies all job description dictionaries for jobs within a specified domain. This function is deprecated. ```swift func SMCopyAllJobDictionaries(CFString!) -> Unmanaged! ``` -------------------------------- ### SMAppService.Status Enumeration Source: https://developer.apple.com/documentation/servicemanagement/smappservice/status-swift.enum/enabled Defines the possible registration and operational states for a service managed by SMAppService. ```APIDOC ## SMAppService.Status ### Description Represents the current registration and operational status of a service. ### Constants - **enabled**: The service has been successfully registered and is eligible to run. - **notRegistered**: The service hasn’t registered with the Service Management framework, or the service attempted to reregister after it was already registered. - **requiresApproval**: The service has been successfully registered, but the user needs to take action in System Preferences. - **notFound**: An error occurred and the framework couldn’t find this service. ### Compatibility - Mac Catalyst 13.0+ - macOS 10.6+ ``` -------------------------------- ### unregister() Source: https://developer.apple.com/documentation/servicemanagement/smappservice/unregister%28%29 Unregisters the service so the system no longer launches it. ```APIDOC ## unregister() ### Description Unregisters the service so the system no longer launches it. This is the opposite operation of register(). If the service corresponds to a LoginItem, LaunchAgent, or LaunchDaemon and is currently running, the system terminates it. If the service corresponds to the main application, it continues running but becomes unregistered to prevent future launches at login. ### Method Instance Method ### Syntax func unregister() throws ### Discussion If the service is already unregistered, this method returns kSMErrorJobNotFound. ### Availability - Mac Catalyst 16.0+ - macOS 13.0+ ``` -------------------------------- ### kSMErrorInvalidPlist Source: https://developer.apple.com/documentation/servicemanagement/ksmerrorinvalidplist The app's property list is invalid. Available on Mac Catalyst 13.0+ and macOS 10.6+. ```APIDOC ## Global Variable ### kSMErrorInvalidPlist The app’s property list is invalid. **Availability:** Mac Catalyst 13.0+ macOS 10.6+ ```swift var kSMErrorInvalidPlist: Int { get } ``` ``` -------------------------------- ### Unregister Service with Completion Handler Source: https://developer.apple.com/documentation/servicemanagement/smappservice/unregister%28completionhandler%3A%29 Unregisters the service so the system no longer launches it and calls a completion handler you provide with the resulting error value. ```APIDOC ## POST /websites/developer_apple_servicemanagement/unregister ### Description Unregisters the service so the system no longer launches it and calls a completion handler you provide with the resulting error value. ### Method POST ### Endpoint /websites/developer_apple_servicemanagement/unregister ### Parameters #### Query Parameters - **handler** (completion handler) - Required - A completion handler to call with the result of the unregistration operation. Upon an unsuccessful return, the handler contains a new `NSError` object describing the error. Upon successful return, this argument is `NULL`. ### Request Example ```json { "handler": "@escaping @Sendable ((any Error)?) -> Void" } ``` ### Response #### Success Response (200) - **error** (NSError?) - An error object describing the error if the unregistration was unsuccessful, otherwise NULL. #### Response Example ```json { "error": null } ``` ``` -------------------------------- ### SMJobSubmit Source: https://developer.apple.com/documentation/servicemanagement/smjobcopydictionary%28_%3A_%3A%29 Submits the specified job to the specified domain. ```APIDOC ## SMJobSubmit ### Description Submits the specified job to the specified domain. ``` -------------------------------- ### Submit Job - Swift Source: https://developer.apple.com/documentation/servicemanagement/smjobcopydictionary%28_%3A_%3A%29 Submits a specified job to the given domain. This function is deprecated and requires error handling. ```swift func SMJobSubmit(CFString!, CFDictionary, UnsafeMutableRawPointer!, UnsafeMutablePointer?>!) -> Bool ``` -------------------------------- ### Check Legacy Login Item Status Source: https://developer.apple.com/documentation/servicemanagement/smappservice/statusforlegacyplist%28at%3A%29 Use this method to determine the authorization status of a legacy login item by providing the URL to its property list. Available on Mac Catalyst 16.0+ and macOS 13.0+. ```swift class func statusForLegacyPlist(at url: URL) -> SMAppService.Status ``` -------------------------------- ### Unregister a Service with unregister() Source: https://developer.apple.com/documentation/servicemanagement/smappservice/register%28%29 Unregisters the service so the system no longer launches it. This method is available on Mac Catalyst 16.0+ and macOS 13.0+. ```swift func unregister() throws ``` -------------------------------- ### Define kSMErrorJobPlistNotFound Source: https://developer.apple.com/documentation/servicemanagement/ksmerrorjobplistnotfound Represents the error constant indicating that a job property list was not found. ```swift var kSMErrorJobPlistNotFound: Int { get } ```