IMServiceApplication Protocol Reference

Conforms to	NSObject
Framework	/System/Library/Frameworks/IMServicePlugIn.framework
Availability	Available in OS X v10.7 and later.
Declared in	IMServicePlugInProtocols.h IMServicePlugInTypes.h

Overview

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.

Tasks

Communicating with the Instant Messaging Client

Instance Methods

plugInDidFailToAuthenticate

Indicates that the session failed to authenticate with the instant message service. (required)

- (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.

Availability

Available in OS X v10.7 and later.

Declared In

IMServicePlugInProtocols.h

plugInDidLogIn

Indicates that the session logged in. (required)

- (oneway void)plugInDidLogIn

Discussion

Availability

Available in OS X v10.7 and later.

Declared In

IMServicePlugInProtocols.h

plugInDidLogOutWithError:reconnect:

Indicates that the session logged out. (required)

- (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

Availability

Available in OS X v10.7 and later.

Declared In

IMServicePlugInProtocols.h

plugInDidUpdateProperties:ofHandle:

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

- (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.

Availability

Available in OS X v10.7 and later.

Declared In

IMServicePlugInProtocols.h

Constants

Handle Properties

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

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

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

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

IMHandlePropertyStatusMessage

The handle’s current status message. (NSString)

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

IMHandlePropertyAuthorizationStatus

The authorization status. (IMHandleAuthorizationStatus as an NSNumber)

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

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.

Declared in IMServicePlugInTypes.h.

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.

Declared in IMServicePlugInTypes.h.

IMHandlePropertyFirstName

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

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

IMHandlePropertyLastName

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

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

IMHandlePropertyEmailAddress

The email address of the handle. (NSString)

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

IMHandlePropertyPictureIdentifier

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

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

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.

Declared in IMServicePlugInTypes.h.

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.

Declared in IMServicePlugInTypes.h.

Handle Availability

Handle availability states.

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

Constants

IMHandleAvailabilityUnknown

Unknown availability.

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

IMHandleAvailabilityOffline

Offline.

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

IMHandleAvailabilityAway

Away.

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

IMHandleAvailabilityAvailable

Available.

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

Handle Authorization Status

Authorization request statuses.

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

Constants

IMHandleAuthorizationStatusAccepted

Request was accepted.

The user can see the handle’s online status.

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

IMHandleAuthorizationStatusPending

Request is pending.

The request has been sent and is pending approval.

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

IMHandleAuthorizationStatusDeclined

Request was declined.

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

Discussion

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

Handle Capabilities

Values for the IMHandlePropertyCapabilities key.

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

Constants

IMHandleCapabilityMessaging

The handle can send and receive instant messages.

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

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.

Declared in IMServicePlugInTypes.h.

IMHandleCapabilityChatRoom

The handle can participate in chat rooms.

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

IMHandleCapabilityHandlePicture

The handle can have a picture.

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

IMHandleCapabilityFileTransfer

The handle can send and receive files.

Available in OS X v10.7 and later.

Declared in IMServicePlugInTypes.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.