servicemanagement

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 30, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package servicemanagement provides Go bindings for the ServiceManagement framework.

Manage startup items, launch agents, and launch daemons from within an app.

Use Service Management to install and observe the permission settings of three supplemental helper executables that macOS supports. You can use all three of these to provide additional functionality related to your app, from inside your app’s bundle:

Essentials

  • Updating helper executables from earlier versions of macOS: Simplify your app’s helper executables and support new authorization controls.
  • Updating your app package installer to use the new Service Management API: Learn about the Service Management API with a GUI-less agent app.

Management

  • SMAppService: An object the framework uses to control helper executables that live inside an app’s main bundle.
  • SMJobBless(_:_:_:_:): Submits the executable for the given label as a job to .
  • Authorization Constants: Constants that describe the ability to authorize helper executables or modify daemon applications.
  • Property List Keys: Property list keys that describe the kinds of applications, daemons, and helper executables the framework manages.

Enablement

  • SMLoginItemSetEnabled(_:_:): Enables a helper executable in the main app-bundle directory.

Status

  • SMAppService.Status: Constants that describe the registration or authorization status of a helper executable.

Errors

  • Service Management Errors: Errors that the framework returns.

Deprecated

  • Deprecated Symbols

Variables

  • SMAppServiceErrorDomain

Key Types

  • SMAppService - An object the framework uses to control helper executables that live inside an app’s main bundle.

Code generated from Apple documentation. DO NOT EDIT.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// KSMDomainSystemLaunchd is the system-level launch domain.
	//
	// See: https://developer.apple.com/documentation/ServiceManagement/kSMDomainSystemLaunchd
	KSMDomainSystemLaunchd string
	// KSMDomainUserLaunchd is the user-level launch domain.
	//
	// See: https://developer.apple.com/documentation/ServiceManagement/kSMDomainUserLaunchd
	KSMDomainUserLaunchd string
)
View Source 
var (
	// See: https://developer.apple.com/documentation/ServiceManagement/SMAppServiceErrorDomain
	SMAppServiceErrorDomain string
)

Functions

func NewErrorBlock 

func NewErrorBlock(handler ErrorHandler) (objc.ID, func())

NewErrorBlock wraps a Go ErrorHandler as an Objective-C block. The caller must defer the returned cleanup function.

Used by:

func SMCopyAllJobDictionaries deprecated 

func SMCopyAllJobDictionaries(domain corefoundation.CFStringRef) corefoundation.CFArrayRef

SMCopyAllJobDictionaries copies the job description dictionaries for all jobs in the specified domain.

Deprecated: Deprecated since macOS 10.10.

See: https://developer.apple.com/documentation/ServiceManagement/SMCopyAllJobDictionaries(_:)

func SMJobCopyDictionary deprecated 

func SMJobCopyDictionary(domain corefoundation.CFStringRef, jobLabel corefoundation.CFStringRef) corefoundation.CFDictionaryRef

SMJobCopyDictionary copies the job description dictionary for the specified job label.

Deprecated: Deprecated since macOS 10.10.

See: https://developer.apple.com/documentation/ServiceManagement/SMJobCopyDictionary(_:_:)

func SMJobRemove deprecated 

func SMJobRemove(domain corefoundation.CFStringRef, jobLabel corefoundation.CFStringRef, auth unsafe.Pointer, wait bool, outError *corefoundation.CFErrorRef) bool

SMJobRemove removes the job with the specified label from the specified domain.

Deprecated: Deprecated since macOS 10.10.

See: https://developer.apple.com/documentation/ServiceManagement/SMJobRemove(_:_:_:_:_:)

func SMJobSubmit deprecated 

func SMJobSubmit(domain corefoundation.CFStringRef, job corefoundation.CFDictionaryRef, auth unsafe.Pointer, outError *corefoundation.CFErrorRef) bool

SMJobSubmit submits the specified job to the specified domain.

Deprecated: Deprecated since macOS 10.10.

See: https://developer.apple.com/documentation/ServiceManagement/SMJobSubmit(_:_:_:_:)

Types

type ErrorHandler 

type ErrorHandler = func(error)

ErrorHandler handles A completion handler to call with the result of the unregistration operation. The error can be type-asserted to *foundation.NSError for Domain, Code, and UserInfo.

Used by:

type ISMAppService 

type ISMAppService interface {
	objectivec.IObject

	// Registers the service so it can begin launching subject to user approval.
	RegisterAndReturnError() (bool, error)
	// Unregisters the service so the system no longer launches it.
	UnregisterAndReturnError() (bool, error)
	// Unregisters the service so the system no longer launches it and calls a completion handler you provide with the resulting error value.
	UnregisterWithCompletionHandler(handler ErrorHandler)

	// A property that describes registration or authorization state of the service.
	Status() SMAppServiceStatus
}

An interface definition for the SMAppService class.

Registering services

  • [ISMAppService.RegisterAndReturnError]: Registers the service so it can begin launching subject to user approval.
  • [ISMAppService.UnregisterAndReturnError]: Unregisters the service so the system no longer launches it.
  • [ISMAppService.UnregisterWithCompletionHandler]: Unregisters the service so the system no longer launches it and calls a completion handler you provide with the resulting error value.

Getting the state of the service

  • [ISMAppService.Status]: A property that describes registration or authorization state of the service.

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService

type KSMError 

type KSMError int
const (
	// KSMErrorAlreadyRegistered: The application is already registered.
	KSMErrorAlreadyRegistered KSMError = 12
	// KSMErrorAuthorizationFailure: The authorization requested failed.
	KSMErrorAuthorizationFailure KSMError = 4
	// KSMErrorInternalFailure: An internal failure has occurred.
	KSMErrorInternalFailure KSMError = 2
	// KSMErrorInvalidPlist: The app’s property list is invalid.
	KSMErrorInvalidPlist KSMError = 10
	// KSMErrorInvalidSignature: The app’s code signature doesn’t meet the requirements to perform the operation.
	KSMErrorInvalidSignature KSMError = 3
	KSMErrorJobMustBeEnabled KSMError = 9
	// KSMErrorJobNotFound: The system can’t find the specified job.
	KSMErrorJobNotFound      KSMError = 6
	KSMErrorJobPlistNotFound KSMError = 8
	// KSMErrorLaunchDeniedByUser: The user denied the app’s launch request.
	KSMErrorLaunchDeniedByUser KSMError = 11
	// KSMErrorServiceUnavailable: The service necessary to perform this operation is unavailable or is no longer accepting requests.
	KSMErrorServiceUnavailable KSMError = 7
	// KSMErrorToolNotValid: The specified path doesn’t exist or the helper tool at the specified path isn’t valid.
	KSMErrorToolNotValid KSMError = 5
)

func (KSMError) String 

func (e KSMError) String() string

type SMAppService 

type SMAppService struct {
	objectivec.Object
}

An object the framework uses to control helper executables that live inside an app’s main bundle.

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 SMAppService.RegisterAndReturnError and SMAppService.UnregisterAndReturnError APIs provide a replacement for SMLoginItemSetEnabled(_:_:). - For [SMAppServices] initialized as [LaunchAgents], the SMAppService.RegisterAndReturnError and SMAppService.UnregisterAndReturnError methods provide a replacement for installing property lists in `~/Library/LaunchAgents` or `/Library/LaunchAgents`. - For [SMAppServices] initialized as [LaunchDaemons], the SMAppService.RegisterAndReturnError and SMAppService.UnregisterAndReturnError methods provide a replacement for installing property lists in `/Library/LaunchDaemons`.

Registering services

Getting the state of the service

  • SMAppService.Status: A property that describes registration or authorization state of the service.

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService

func NewSMAppService 

func NewSMAppService() SMAppService

NewSMAppService creates a new SMAppService instance.

func SMAppServiceFromID 

func SMAppServiceFromID(id objc.ID) SMAppService

SMAppServiceFromID constructs a SMAppService from an objc.ID.

An object the framework uses to control helper executables that live inside an app’s main bundle.

func (SMAppService) Autorelease 

func (a SMAppService) Autorelease() SMAppService

Autorelease adds the receiver to the current autorelease pool.

func (SMAppService) Init 

func (a SMAppService) Init() SMAppService

Init initializes the instance.

func (SMAppService) RegisterAndReturnError 

func (a SMAppService) RegisterAndReturnError() (bool, error)

Registers the service so it can begin launching subject to user approval.

Discussion

The registration process applies to the following rules, depending upon the type of service:

- If the service corresponds to a LoginItem bundle, the helper starts immediately and on subsequent logins. If the helper crashes or exits with a non-zero status, the system relaunches it. - If the service corresponds to the main application, the application launches on subsequent logins. - If the service corresponds to a LaunchAgent, the LaunchAgent is immediately bootstrapped and may begin running. In addition LaunchAgents registered with this method bootstrap on each subsequent login. - If an app needs to register a LaunchAgent for multiple users, you must call the API once per user while that user is running the app. - If the service corresponds to a LaunchDaemon, the system won’t bootstrap the LaunchDaemon until an admin approves the LaunchDaemon in System Preferences. The system bootstraps LaunchDaemons registered with this method and approved by an admin on each subsequent boot.

If the service is already registered, this method returns KSMErrorAlreadyRegistered.

If the service isn’t approved by the user, this method returns KSMErrorLaunchDeniedByUser.

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService/register()

func (SMAppService) Status 

func (a SMAppService) Status() SMAppServiceStatus

A property that describes registration or authorization state of the service.

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService/status-swift.property

func (SMAppService) Unregister 

func (a SMAppService) Unregister(ctx context.Context) error

Unregister is a synchronous wrapper around SMAppService.UnregisterWithCompletionHandler. It blocks until the completion handler fires or the context is cancelled.

func (SMAppService) UnregisterAndReturnError 

func (a SMAppService) UnregisterAndReturnError() (bool, error)

Unregisters the service so the system no longer launches it.

Discussion

This is the opposite operation of [RegisterAndReturnError].

If the service corresponds to a LoginItem, LaunchAgent, or LaunchDaemon and the service is currently running it, the system terminates it. If the service corresponds to the main application, it continues running, but becomes unregistered to prevent future launches at login.

If the service is already unregistered, this method returns KSMErrorJobNotFound.

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService/unregister()

func (SMAppService) UnregisterWithCompletionHandler 

func (a SMAppService) UnregisterWithCompletionHandler(handler ErrorHandler)

Unregisters the service so the system no longer launches it and calls a completion handler you provide with the resulting error value.

handler: 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].

Discussion

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService/unregister(completionHandler:)

type SMAppServiceClass 

type SMAppServiceClass struct {
	// contains filtered or unexported fields
}

func GetSMAppServiceClass 

func GetSMAppServiceClass() SMAppServiceClass

GetSMAppServiceClass returns the class object for SMAppService.

func (SMAppServiceClass) AgentServiceWithPlistName 

func (_SMAppServiceClass SMAppServiceClass) AgentServiceWithPlistName(plistName string) SMAppService

Initializes an app service object with a launch agent with the property list name you provide.

plistName: The name of the property list corresponding to the SMAppService.

Discussion

The property list name must correspond to a property list in the calling app’s `Contents/Library/LaunchAgents` directory.

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService/agent(plistName:)

func (SMAppServiceClass) Alloc 

func (sc SMAppServiceClass) Alloc() SMAppService

Alloc allocates memory for a new instance of the class.

func (SMAppServiceClass) Class 

func (sc SMAppServiceClass) Class() objc.Class

Class returns the underlying Objective-C class pointer.

func (SMAppServiceClass) DaemonServiceWithPlistName 

func (_SMAppServiceClass SMAppServiceClass) DaemonServiceWithPlistName(plistName string) SMAppService

Initializes an app service object with a launch daemon with the property list name you provide.

plistName: The name of the property list corresponding to the SMAppService.

Return Value

An [SMService] object

Discussion

The property list name must correspond to a property list in the calling app’s `Contents/Library/LaunchDaemons` directory

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService/daemon(plistName:)

func (SMAppServiceClass) LoginItemServiceWithIdentifier 

func (_SMAppServiceClass SMAppServiceClass) LoginItemServiceWithIdentifier(identifier string) SMAppService

Initializes an app service object for a login item corresponding to the bundle with the identifier you provide.

identifier: The bundle identifier of the helper application.

Return Value

An [SMService] object.

Discussion

The property list name must correspond to a property list in the calling app’s `Contents/Library/LoginItems` directory

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService/loginItem(identifier:)

func (SMAppServiceClass) MainAppService 

func (_SMAppServiceClass SMAppServiceClass) MainAppService() SMAppService

An app service object that corresponds to the main application as a login item.

Discussion

Use this SMAppService to configure the main app to launch at login.

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService/mainApp

func (SMAppServiceClass) OpenSystemSettingsLoginItems 

func (_SMAppServiceClass SMAppServiceClass) OpenSystemSettingsLoginItems()

Opens System Settings to the Login Items control panel.

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService/openSystemSettingsLoginItems()

func (SMAppServiceClass) StatusForLegacyURL 

func (_SMAppServiceClass SMAppServiceClass) StatusForLegacyURL(url foundation.INSURL) SMAppServiceStatus

Check the authorization status of an earlier OS version login item.

url: The URL of the helper executable’s property list.

Return Value

One of the SMAppService.Status constants that indicate the current authorization status.

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService/statusForLegacyPlist(at:)

type SMAppServiceStatus 

type SMAppServiceStatus int

See: https://developer.apple.com/documentation/ServiceManagement/SMAppService/Status-swift.enum 

const (
	// SMAppServiceStatusEnabled: The service has been successfully registered and is eligible to run.
	SMAppServiceStatusEnabled SMAppServiceStatus = 1
	// SMAppServiceStatusNotFound: An error occurred and the framework couldn’t find this service.
	SMAppServiceStatusNotFound SMAppServiceStatus = 3
	// SMAppServiceStatusNotRegistered: The service hasn’t registered with the Service Management framework, or the service attempted to reregister after it was already registered.
	SMAppServiceStatusNotRegistered SMAppServiceStatus = 0
	// SMAppServiceStatusRequiresApproval: The service has been successfully registered, but the user needs to take action in System Preferences.
	SMAppServiceStatusRequiresApproval SMAppServiceStatus = 2
)

func (SMAppServiceStatus) String 

func (e SMAppServiceStatus) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.