Mac Developer Library

Developer

IMServicePlugIn Framework Reference IMServiceApplication Protocol Reference

Options
Deployment Target:

On This Page
Language:

IMServiceApplication

A service plug-in communicates with the instant messaging client using the IMServiceApplication protocol. An object implementing this protocol is passed to your service plug-in by the initWithServiceApplication: method.

Inheritance


Not Applicable

Import Statement


import IMServicePlugIn @import IMServicePlugIn;

Availability


Available in OS X v10.7 and later.
  • Indicates that the session failed to authenticate with the instant message service. (required)

    Declaration

    Swift

    func plugInDidFailToAuthenticate()

    Objective-C

    - (oneway void)plugInDidFailToAuthenticate

    Discussion

    The instant messaging client re-requests the user name and password and either calls the IMServicePlugIn updateAccountSettings: method with the new settings or, if the user cancels, calls the IMServicePlugIn logout method.

    Import Statement

    import IMServicePlugIn

    Availability

    Available in OS X v10.7 and later.

  • Indicates that the session logged in. (required)

    Declaration

    Swift

    func plugInDidLogIn()

    Objective-C

    - (oneway void)plugInDidLogIn

    Discussion

    Import Statement

    import IMServicePlugIn

    Availability

    Available in OS X v10.7 and later.

  • Indicates that the session logged out. (required)

    Declaration

    Swift

    func plugInDidLogOutWithError(_ error: NSError!, reconnect reconnect: Bool)

    Objective-C

    - (oneway void)plugInDidLogOutWithError:(NSError *)error reconnect:(BOOL)reconnect

    Parameters

    error

    The error, if any, that caused the disconnection. If this method is called in response to the IMServicePlugIn logout method being called, error should be nil.

    reconnect

    A Boolean value indicating whether the instant messaging client should try to reconnect.

    Discussion

    Import Statement

    import IMServicePlugIn

    Availability

    Available in OS X v10.7 and later.

  • Indicates that one or more properties of a handle have changed. (required)

    Declaration

    Swift

    func plugInDidUpdateProperties(_ changes: [NSObject : AnyObject]!, ofHandle handle: String!)

    Objective-C

    - (oneway void)plugInDidUpdateProperties:(NSDictionary *)changes ofHandle:(NSString *)handle

    Parameters

    changes

    A dictionary of the new handle properties for the handle. For a list of keys, see Handle Properties.

    handle

    A handle.

    Discussion

    This method should also be called once for each handle in the updated group list after the plugInDidUpdateGroupList:error: method is called.

    Import Statement

    import IMServicePlugIn

    Availability

    Available in OS X v10.7 and later.

  • Keys used in the dictionary passed to the plugInDidUpdateProperties:ofHandle: method.

    Declaration

    Swift

    let IMHandlePropertyAvailability: NSString! let IMHandlePropertyStatusMessage: NSString! let IMHandlePropertyAuthorizationStatus: NSString! let IMHandlePropertyIdleDate: NSString! let IMHandlePropertyAlias: NSString! let IMHandlePropertyFirstName: NSString! let IMHandlePropertyLastName: NSString! let IMHandlePropertyEmailAddress: NSString! let IMHandlePropertyPictureIdentifier: NSString! let IMHandlePropertyPictureData: NSString! let IMHandlePropertyCapabilities: NSString!

    Objective-C

    NSString * const IMHandlePropertyAvailability; NSString * const IMHandlePropertyStatusMessage; NSString * const IMHandlePropertyAuthorizationStatus; NSString * const IMHandlePropertyIdleDate; NSString * const IMHandlePropertyAlias; NSString * const IMHandlePropertyFirstName; NSString * const IMHandlePropertyLastName; NSString * const IMHandlePropertyEmailAddress; NSString * const IMHandlePropertyPictureIdentifier; NSString * const IMHandlePropertyPictureData; NSString * const IMHandlePropertyCapabilities;

    Constants

    • IMHandlePropertyAvailability

      IMHandlePropertyAvailability

      The availability of the handle. (IMHandleAvailability as an NSNumber)

      Available in OS X v10.7 and later.

    • IMHandlePropertyStatusMessage

      IMHandlePropertyStatusMessage

      The handle’s current status message. (NSString)

      Available in OS X v10.7 and later.

    • IMHandlePropertyAuthorizationStatus

      IMHandlePropertyAuthorizationStatus

      The authorization status. (IMHandleAuthorizationStatus as an NSNumber)

      Available in OS X v10.7 and later.

    • IMHandlePropertyIdleDate

      IMHandlePropertyIdleDate

      The time of the last user activity (NSDate).

      This key is applicable only for idle handles. To indicate that the time is unknown, use the value returned by the NSDate method distantPast.

      Available in OS X v10.7 and later.

    • IMHandlePropertyAlias

      IMHandlePropertyAlias

      A nicely formatted version of the handle (for example, with whitespace and capitalization).

      If none is available, omit this property.

      Available in OS X v10.7 and later.

    • IMHandlePropertyFirstName

      IMHandlePropertyFirstName

      The first name (given name) of the handle. (NSString)

      Available in OS X v10.7 and later.

    • IMHandlePropertyLastName

      IMHandlePropertyLastName

      The last name (family name) of the handle. (NSString)

      Available in OS X v10.7 and later.

    • IMHandlePropertyEmailAddress

      IMHandlePropertyEmailAddress

      The email address of the handle. (NSString)

      Available in OS X v10.7 and later.

    • IMHandlePropertyPictureIdentifier

      IMHandlePropertyPictureIdentifier

      A unique identifier for the handle’s picture. (NSString)

      Available in OS X v10.7 and later.

    • IMHandlePropertyPictureData

      IMHandlePropertyPictureData

      The handle’s picture. (NSData)

      Include this key only when responding to the requestPictureForHandle:withIdentifier: method.

      Available in OS X v10.7 and later.

    • IMHandlePropertyCapabilities

      IMHandlePropertyCapabilities

      The handle’s capabilities. (NSArray of capabilities)

      For a list of handle capabilities, see Handle Capabilities

      Available in OS X v10.7 and later.

    Import Statement

  • Handle availability states.

    Declaration

    Swift

    enum IMHandleAvailability : Int { case Unknown case Offline case Away case Available }

    Objective-C

    enum { IMHandleAvailabilityUnknown = -2, IMHandleAvailabilityOffline = -1, IMHandleAvailabilityAway = 0, IMHandleAvailabilityAvailable = 1 }; typedef NSInteger IMHandleAvailability;

    Constants

    • Unknown

      IMHandleAvailabilityUnknown

      Unknown availability.

      Available in OS X v10.7 and later.

    • Offline

      IMHandleAvailabilityOffline

      Offline.

      Available in OS X v10.7 and later.

    • Away

      IMHandleAvailabilityAway

      Away.

      Available in OS X v10.7 and later.

    • Available

      IMHandleAvailabilityAvailable

      Available.

      Available in OS X v10.7 and later.

    Import Statement

    import IMServicePlugIn

    Availability

    Available in OS X v10.7 and later.

  • Authorization request statuses.

    Declaration

    Swift

    enum IMHandleAuthorizationStatus : Int { case Accepted case Pending case Declined }

    Objective-C

    enum { IMHandleAuthorizationStatusAccepted = 0, IMHandleAuthorizationStatusPending = 1, IMHandleAuthorizationStatusDeclined = 2 }; typedef NSInteger IMHandleAuthorizationStatus;

    Constants

    • Accepted

      IMHandleAuthorizationStatusAccepted

      Request was accepted.

      The user can see the handle’s online status.

      Available in OS X v10.7 and later.

    • Pending

      IMHandleAuthorizationStatusPending

      Request is pending.

      The request has been sent and is pending approval.

      Available in OS X v10.7 and later.

    • Declined

      IMHandleAuthorizationStatusDeclined

      Request was declined.

      Available in OS X v10.7 and later.

    Discussion

    The IMServicePlugInGroupListAuthorizationSupport Protocol Reference and IMServiceApplicationGroupListAuthorizationSupport protocols are used to interact with authorization requests.

    Import Statement

    import IMServicePlugIn

    Availability

    Available in OS X v10.7 and later.

  • Values for the IMHandlePropertyCapabilities key.

    Declaration

    Swift

    let IMHandleCapabilityMessaging: NSString! let IMHandleCapabilityOfflineMessaging: NSString! let IMHandleCapabilityChatRoom: NSString! let IMHandleCapabilityHandlePicture: NSString! let IMHandleCapabilityFileTransfer: NSString!

    Objective-C

    NSString * const IMHandleCapabilityMessaging; NSString * const IMHandleCapabilityOfflineMessaging; NSString * const IMHandleCapabilityChatRoom; NSString * const IMHandleCapabilityHandlePicture; NSString * const IMHandleCapabilityFileTransfer;

    Constants

    • IMHandleCapabilityMessaging

      IMHandleCapabilityMessaging

      The handle can send and receive instant messages.

      Available in OS X v10.7 and later.

    • IMHandleCapabilityOfflineMessaging

      IMHandleCapabilityOfflineMessaging

      The handle can receive instant messages when offline.

      Some instant messaging services store messages that are sent to offline handles and deliver the messages when the users log back in.

      Available in OS X v10.7 and later.

    • IMHandleCapabilityChatRoom

      IMHandleCapabilityChatRoom

      The handle can participate in chat rooms.

      Available in OS X v10.7 and later.

    • IMHandleCapabilityHandlePicture

      IMHandleCapabilityHandlePicture

      The handle can have a picture.

      Available in OS X v10.7 and later.

    • IMHandleCapabilityFileTransfer

      IMHandleCapabilityFileTransfer

      The handle can send and receive files.

      Available in OS X v10.7 and later.

    Import Statement