IMService Class Reference

Overview

The IMService class provides methods for getting information about an instant message service. Each IMService object represents one service available through iChat. Class methods such as allServices and serviceWithName: return these objects. Each object represents a single instant messaging service, allowing you to access the iChat status of the user, the user's list of buddies, and other information that can be integrated into your application. A variety of status notifications related to the user's status and preferences are posted by the IMService custom notification center.

Tasks

Accessing Instant Messaging Services

• + allServices
• + serviceWithName:

Accessing Service Attributes

• + imageNameForStatus:
• + myIdleTime
• + myStatus
• + notificationCenter
• – localizedName
• – localizedShortName
• – name
• – status
• + imageURLForStatus: Deprecated in Mac OS X v10.5

Accessing Buddies

• – peopleWithScreenName:
• – screenNamesForPerson:
• – infoForAllScreenNames
• – infoForPreferredScreenNames
• – infoForScreenName:

Class Methods

allServices

Returns an array of the currently available services.

+ (NSArray *)allServices

Return Value

Returns an NSArray of IMService objects corresponding to the current available services (AIM, Bonjour, and so on.).

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + serviceWithName:

Declared In

IMService.h

imageNameForStatus:

Returns the name of the image for the specified status of a person.

+ (NSString *)imageNameForStatus:(IMPersonStatus)status

Parameters

status

The status of a person. See “IMPersonStatus” for possible values.

Return Value

The name of an image that reflects the current online status of a person; it is usually a colored bubble or triangle.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• + myStatus

Related Sample Code

• ABPresence

Declared In

IMService.h

myIdleTime

Returns the number of seconds that the current user is idle.

+ (NSDate *)myIdleTime

Return Value

The number of seconds that the current user is idle.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

IMService.h

myStatus

Returns the status of the current user.

+ (IMPersonStatus)myStatus

Return Value

A code representing the status of the current user. See “IMPersonStatus” for possible values.

Discussion

This status is global across all services.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + imageNameForStatus:

Declared In

IMService.h

notificationCenter

Returns the custom notification center for the service.

+ (NSNotificationCenter *)notificationCenter

Return Value

A custom notification center that manages IMService notifications.

Availability

• Available in Mac OS X v10.4 and later.

Related Sample Code

• ABPresence
• iChatTheater

Declared In

IMService.h

serviceWithName:

Returns the specified service.

+ (IMService *)serviceWithName:(NSString *)name

Parameters

name

A service name as returned by a previous call to the name method. Hard-coding the service names is not recommended.

Return Value

The service specified by name.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• + allServices
• – name

Declared In

IMService.h

Instance Methods

infoForAllScreenNames

Returns information about all buddies for the service.

- (NSArray *)infoForAllScreenNames

Return Value

The dictionaries returned by infoForScreenName: for all buddies.

Discussion

If the current user has multiple buddies for the same person (determined by the user's Address Book), this method returns the information for all of the accounts belonging to that person.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – infoForPreferredScreenNames
• – infoForScreenName:

Declared In

IMService.h

infoForPreferredScreenNames

Returns information about just the preferred accounts for all buddies.

- (NSArray *)infoForPreferredScreenNames

Return Value

An array of the dictionaries returned by infoForScreenName: for all preferred accounts.

Discussion

If the current user has multiple buddies for the same person (determined by the user's Address Book), this method returns only the information for the preferred accounts belonging to that person. The preferred account is determined by iChat, using a combination of capabilities (video chat capability, audio chat capability, and so on), status (available, idle, away), and other user attributes.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – infoForAllScreenNames
• – infoForScreenName:

Declared In

IMService.h

infoForScreenName:

Returns information about a buddy with the specified screen name.

- (NSDictionary *)infoForScreenName:(NSString *)screenName

Parameters

screenName

A screen name for a buddy.

Return Value

Information about a buddy with the specified screen name. See “Screen Name Properties” for the key-value pairs that appear in this dictionary.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – infoForAllScreenNames
• – infoForPreferredScreenNames

Declared In

IMService.h

localizedName

Returns the user-visible localized name of the service.

- (NSString *)localizedName

Return Value

The user-visible localized name of the service, such as "AOL Instant Messenger" or "Bonjour".

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – localizedShortName
• – name

Declared In

IMService.h

localizedShortName

Returns a short version, if available, of the user-visible localized name of the service.

- (NSString *)localizedShortName

Return Value

The user-visible short localized name of the service, such as "AOL".

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – localizedName
• – name

Declared In

IMService.h

name

Returns the fixed canonical name of the service.

- (NSString *)name

Return Value

The fixed canonical name of the service. This string is not intended to be visible to the user and therefore is not localized.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – localizedName
• – localizedShortName

Declared In

IMService.h

peopleWithScreenName:

Returns Address Book entries that match the specified screen name of a buddy.

- (NSArray *)peopleWithScreenName:(NSString *)screenName

Parameters

screenName

The screen name of a buddy.

Return Value

An array of Address Book entries that match the specified screen name of a buddy. Returns an empty array if there is no match.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – screenNamesForPerson:

Related Sample Code

• ABPresence

Declared In

IMService.h

screenNamesForPerson:

Returns an array of strings that are valid screen names for the specified person.

- (NSArray *)screenNamesForPerson:(ABPerson *)person

Parameters

person

An entry in the Address Book.

Return Value

An array of valid screen names for the specified person. Returns an empty array if there is no match.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – peopleWithScreenName:

Declared In

IMService.h

status

Returns the login status of the service.

- (IMServiceStatus)status

Return Value

The login status of the service. One of the constants described in “IMServiceStatus.”

Availability

• Available in Mac OS X v10.4 and later.

Declared In

IMService.h

Constants

Screen Name Properties

Keys for information about a person logged in to an instant message service—specifically, a buddy that appears in the user’s buddy list:

extern NSString *IMPersonAVBusyKey;
extern NSString *IMPersonCapabilitiesKey;
extern NSString *IMPersonEmailKey;
extern NSString *IMPersonFirstNameKey;
extern NSString *IMPersonIdleSinceKey;
extern NSString *IMPersonLastNameKey;
extern NSString *IMPersonPictureDataKey;
extern NSString *IMPersonScreenNameKey;
extern NSString *IMPersonServiceNameKey;
extern NSString *IMPersonStatusKey;
extern NSString *IMPersonStatusMessageKey;

Constants

IMPersonAVBusyKey

Used to obtain a person’s busy status. The value is an NSNumber set to 0 if the person’s audio/video capabilities are available, or 1 if they are busy.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonCapabilitiesKey

Used to obtain a person’s iChat capabilities. The value is an NSArray of capability properties. See “Person Capability Values” for more information.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonEmailKey

Used to obtain a person’s email address. The value is an NSString containing the person's email address. This is a key used directly by Bonjour; however, if a person has an Address Book entry associated with a relevant AIM account, this key reflects the first email address of that person.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonFirstNameKey

Used to obtain a person’s first name. The value is an NSString containing the person's first name. This is a key used directly by Bonjour; however, if a person has an Address Book entry associated with a relevant AIM account, this key reflects the first name of that person.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonIdleSinceKey

Used to obtain a person’s idle status. The value is an NSDate containing the time, in seconds, since the last user activity. Available if the person’s status is idle.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonLastNameKey

Used to obtain a person’s last name. The value is an NSString containing the person's last name. This is a key used directly by Bonjour; however, if a person has an Address Book entry associated with a relevant AIM account, this key reflects the last name of that person.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonPictureDataKey

Used to obtain a person’s image. The value is an NSData containing the image for the person’s icon.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonScreenNameKey

Used to obtain a person’s screen name. The value is an NSString containing the service-specific identifier for a person. For example, "User123" or "steve@mac.com" for AIM, and "John Doe" for Bonjour.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonServiceNameKey

Used to obtain a person’s service name. The value is an NSString containing the name of the service this person belongs to.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonStatusKey

Used to obtain a person’s online status. The value is an NSNumber representing the current online status of the person, if known. See “IMPersonStatus” for more information.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonStatusMessageKey

Used to obtain a person’s status message. The value is an NSString containing the person’s current status message.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

Discussion

These keys appear in the dictionary returned by the infoForScreenName: method.

Declared In

InstantMessage/IMService.h

Person Capability Values

A person’s iChat capabilities accessed using the IMPersonCapabilitiesKey key.

extern NSString *IMCapabilityAudioConference;
extern NSString *IMCapabilityDirectIM;
extern NSString *IMCapabilityFileSharing;
extern NSString *IMCapabilityFileTransfer;
extern NSString *IMCapabilityText;
extern NSString *IMCapabilityVideoConference;

Constants

IMCapabilityAudioConference

A person has audio chat capability.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMCapabilityDirectIM

A person has direct connect capability.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMCapabilityFileSharing

A person has file sharing capability.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMCapabilityFileTransfer

A person has file transfer capability.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMCapabilityText

A person has text capability.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMCapabilityVideoConference

A person has video chat capability.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

Declared In

InstantMessage/IMService.h

IMServiceStatus

The states of a service.

enum {
   IMServiceStatusLoggedOut,
   IMServiceStatusDisconnected,
   IMServiceStatusLoggingOut,
   IMServiceStatusLoggingIn,
   IMServiceStatusLoggedIn
};
typedef NSUInteger IMServiceStatus;

Constants

IMServiceStatusLoggedOut

A service is currently logged out.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMServiceStatusDisconnected

A service was disconnected, not by the user but by the system or because of an error.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMServiceStatusLoggingOut

A service is in the process of logging out.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMServiceStatusLoggingIn

A service is in the process of logging in.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMServiceStatusLoggedIn

A service is currently logged in.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

Declared In

InstantMessage/IMService.h

IMPersonStatus

The state of a person across all services.

   
enum {
   IMPersonStatusUnknown,
   IMPersonStatusOffline,
   IMPersonStatusIdle,
   IMPersonStatusAway,
   IMPersonStatusAvailable,
   IMPersonStatusNoStatus
};
typedef NSUInteger IMPersonStatus;

Constants

IMPersonStatusUnknown

The person’s status is unknown.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonStatusOffline

The person is currently offline.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonStatusIdle

The person is currently idle.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonStatusAway

The person is currently away.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonStatusAvailable

The person is currently available.

Available in Mac OS X v10.4 and later.

Declared in IMService.h.

IMPersonStatusNoStatus

No status is available.

Available in Mac OS X v10.5 and later.

Declared in IMService.h.

Discussion

This is accessed using the IMPersonStatusKey key for a buddy or returned by the myStatus method for the current user.

Declared In

InstantMessage/IMService.h

Notifications

IMMyStatusChangedNotification

Posted by the IMService custom notification center when the local user changes their online status. The notification object is an IMService object. The user information dictionary does not contain keys. The receiver should send myStatus to the notification object to get the new online status.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

IMService.h

IMPersonInfoChangedNotification

Posted by the IMService custom notification center when a screen name changes some aspect of its published information. The notification object is an IMService object. The user information dictionary always contains the IMPersonServiceNameKey key and may contain any of the other keys as described in “Screen Name Properties”. If a particular attribute is removed, the value for the relevant key is NSNull.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

IMService.h

IMPersonStatusChangedNotification

Posted by the IMService custom notification center when a different buddy (screen name) logs in, logs off, goes away, and so on. The notification object is an IMService object. The user information dictionary always contain the IMPersonScreenNameKey and IMPersonStatusKey keys, and no others.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

IMService.h

IMServiceStatusChangedNotification

Posted by the IMService custom notification center when the status of a service changes—the current user logs in, logs off, goes away, and so on. The notification object is an IMService object. The user information dictionary does not contain keys. The receiver should send status to the notification object to get the new service status.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

IMService.h

IMStatusImagesChangedAppearanceNotification

Posted by the IMService custom notification center when the current user changes his or her preferred images for displaying status. The notification object is nil. This notification does not contain a user information dictionary. Use the imageNameForStatus: method to get the new images.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

IMService.h

---