NSSharingService Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.8 and later.
Declared in
NSSharingService.h
Related sample code

Overview

The NSSharingService class is used to provide a consistent user experience when sharing items on OS X. For example, items can be: NSURL objects, NSString objects, NSImage objects, video (through file URLs), or any object which implements the NSPasteboardWriting protocol.

For any item or group of items, the NSSharingService will display a sharing sheet to allow the user to pre-visualize what will be shared to the service. A sharing service can: create a post on a social network like Twitter or Facebook, send a message by email or iMessage, upload videos to viewing services, or send a file by AirDrop.

It's possible for developers to use NSSharingService directly. For instance, they can create a button that will trigger a service as shown in this code snippet:

- (void)awakeFromNib
{
    NSSharingService * service = [NSSharingService sharingServiceNamed:NSSharingServiceNamePostOnTwitter];
    [myShareOnTwitterButton setTitle:service.title];
    [myShareOnTwitterButton setEnabled:[service canPerformWithItems:nil]];
}
 
 
- (IBAction)shareOnTwitter:(id)sender
{
    // Items to share
    NSAttributedString *text = [self.textView attributedString];
    NSImage *image = [self.imageView image];
    NSArray * shareItems = [NSArray arrayWithObjects:text, image, nil];
 
    NSSharingService *service = [NSSharingService sharingServiceNamed:NSSharingServiceNamePostOnTwitter];
    service.delegate = self;
    [service performWithItems:shareItems];
}

Tasks

Creating a Sharing Service

Available Sharing Services

Sharing Items

Setting Content Attributes

Getting and Setting the Delegate

Obtaining Information About a Completed Post

Properties

accountName

The account name used for posting on Twitter or Sina Weibo. (read-only)

@property(readonly, copy) NSString *accountName
Availability
  • Available in OS X v10.9 and later.
Declared In
NSSharingService.h

alternateImage

The alternate image representing the sharing service. (read-only)

@property(readonly, retain) NSImage *alternateImage
Availability
  • Available in OS X v10.8 and later.
Related Sample Code
Declared In
NSSharingService.h

attachmentFileURLs

An array of NSURL objects representing the files that were shared. (read-only)

@property(readonly, copy) NSArray *attachmentFileURLs
Availability
  • Available in OS X v10.9 and later.
Declared In
NSSharingService.h

delegate

Specifies the delegate of the sharing service.

@property(assign) id<NSSharingServiceDelegate> delegate
Discussion

The delegate class must conform to the NSSharingServiceDelegate protocol.

Availability
  • Available in OS X v10.8 and later.
Related Sample Code
Declared In
NSSharingService.h

image

The primary image representing the sharing service. (read-only)

@property(readonly, retain) NSImage *image
Availability
  • Available in OS X v10.8 and later.
Related Sample Code
Declared In
NSSharingService.h

menuItemTitle

The title of the service in the Share menu.

@property(copy) NSString *menuItemTitle
Discussion

By default, this title is the same as the value of the title property. Your app can modify this value.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSSharingService.h

messageBody

The message body as a string. (read-only)

@property(readonly, copy) NSString *messageBody
Availability
  • Available in OS X v10.9 and later.
Declared In
NSSharingService.h

permanentLink

A permanent URL (permalink) that your app can use to access the post. (read-only)

@property(readonly, copy) NSURL *permanentLink
Availability
  • Available in OS X v10.9 and later.
Declared In
NSSharingService.h

recipients

An array containing the user handles of the desired recipients.

@property(copy) NSArray *recipients
Discussion

Each object in the array is an NSString object that contains the handle of a single recipient. The specific format of these handle varies from service to service. For example, some services use email addresses as handles.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSSharingService.h

subject

The subject of the post.

@property(copy) NSString *subject
Availability
  • Available in OS X v10.9 and later.
Declared In
NSSharingService.h

title

The title of the sharing service. (read-only)

@property(readonly, copy) NSString *title
Availability
  • Available in OS X v10.8 and later.
Related Sample Code
Declared In
NSSharingService.h

Class Methods

sharingServiceNamed:

Returns a sharing service instance representing the specified service name.

+ (NSSharingService *)sharingServiceNamed:(NSString *)serviceName
Parameters
serviceName

The service name. The possible system provided values are listed in “Available Sharing Services.”

Return Value

An instance of NSSharingService for the specified service name.

Availability
  • Available in OS X v10.8 and later.
Related Sample Code
Declared In
NSSharingService.h

sharingServicesForItems:

Returns a list of sharing services which could share all the provided items together.

+ (NSArray *)sharingServicesForItems:(NSArray *)items
Parameters
items

The items to share.

Return Value

An array of sharing services to allow for items.

Discussion

This method can be used to build a custom user interface or to populate a contextual menu.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSSharingService.h

Instance Methods

canPerformWithItems:

Returns whether the service can share all the specified items.

- (BOOL)canPerformWithItems:(NSArray *)items
Parameters
items

The items to share.

Return Value

YES if the service can share all the items; NO otherwise. If items is nil, the method will return YES when the service is configured.

Discussion

This method can be used to validate a custom user interface such as a dedicated Twitter button. Therefore you could call it once at launch time with nil items to check whether to display the button or not, and then with real items to enable and disable the button depending on the context or selection.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSSharingService.h

initWithTitle:image:alternateImage:handler:

Creates a custom sharing service object.

- (id)initWithTitle:(NSString *)title image:(NSImage *)image alternateImage:(NSImage *)alternateImage handler:(void (^)(void))block
Parameters
title

The custom sharing service name.

image

The image that represents the sharing service

alternateImage

The alternate image that represents the sharing service

block

The block that actually interacts with the service.

Return Value

An instance of the custom sharing object.

Discussion

Custom sharing services can be added to the NSSharingServicePicker with the sharingServicePicker:sharingServicesForItems:proposedSharingServices: delegate method.

When implementing this method, consider subclassing NSSharingService so the canPerformWithItems: and sharingServicesForItems: can provide accurate results.

Availability
  • Available in OS X v10.8 and later.
Related Sample Code
Declared In
NSSharingService.h

performWithItems:

Manually performs the service on the provided items.

- (void)performWithItems:(NSArray *)items
Parameters
items

The items to share.

Discussion

In most cases this will display a sharing window.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSSharingService.h

Constants

Available Sharing Services

These constants list the available sharing services.

NSString * const NSSharingServiceNameAddToAperture;
NSString * const NSSharingServiceNameAddToIPhoto;
NSString * const NSSharingServiceNameAddToSafariReadingList;
NSString * const NSSharingServiceNameComposeEmail;
NSString * const NSSharingServiceNameComposeMessage;
NSString * const NSSharingServiceNamePostImageOnFlickr;
NSString * const NSSharingServiceNamePostOnFacebook;
NSString * const NSSharingServiceNamePostOnLinkedIn;
NSString * const NSSharingServiceNamePostOnSinaWeibo;
NSString * const NSSharingServiceNamePostOnTencentWeibo;
NSString * const NSSharingServiceNamePostOnTwitter;
NSString * const NSSharingServiceNamePostVideoOnTudou;
NSString * const NSSharingServiceNamePostVideoOnVimeo;
NSString * const NSSharingServiceNamePostVideoOnYouku;
NSString * const NSSharingServiceNameSendViaAirDrop;
NSString * const NSSharingServiceNameUseAsDesktopPicture;
NSString * const NSSharingServiceNameUseAsFacebookProfileImage;
NSString * const NSSharingServiceNameUseAsLinkedInProfileImage;
NSString * const NSSharingServiceNameUseAsTwitterProfileImage;
Constants
NSSharingServiceNameAddToAperture

Adds the content to Aperture.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNameAddToIPhoto

Adds the content to iPhoto.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNameAddToSafariReadingList

Add the content to the Safari Reading List.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNameComposeEmail

Creates an email messages with the content.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNameComposeMessage

Creates a Messages methods with the content.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNamePostImageOnFlickr

Posts the image on Flickr.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNamePostOnFacebook

Posts the content on Facebook.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNamePostOnLinkedIn

Posts the content on LinkedIn.

Available in OS X v10.9 and later.

Declared in NSSharingService.h.

NSSharingServiceNamePostOnSinaWeibo

Posts the content on a Sina Weibo, Chinese microblogging (weibo) website. Akin to a hybrid of Twitter and Facebook.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNamePostOnTencentWeibo

Posts the content on a Tencent Weibo, Chinese microblogging (weibo) website.

Available in OS X v10.9 and later.

Declared in NSSharingService.h.

NSSharingServiceNamePostOnTwitter

Posts the content on Twitter.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNamePostVideoOnTudou

Posts the video on the video sharing service Tudou, based in the People's Republic of China.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNamePostVideoOnVimeo

Posts the video on the video sharing service Vimeo.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNamePostVideoOnYouku

Posts the video on the video sharing service Youku, based in the People's Republic of China.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNameSendViaAirDrop

Sends the file via Air Drop.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNameUseAsDesktopPicture

Replaces the user’s desktop image with the content.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.

NSSharingServiceNameUseAsFacebookProfileImage

Replaces the user’s Facebook profile image with the provided image.

Available in OS X v10.9 and later.

Declared in NSSharingService.h.

NSSharingServiceNameUseAsLinkedInProfileImage

Replaces the user’s LinkedIn profile image with the provided image.

Available in OS X v10.9 and later.

Declared in NSSharingService.h.

NSSharingServiceNameUseAsTwitterProfileImage

Replaces the user’s Twitter profile image with the provided image.

Available in OS X v10.8 and later.

Declared in NSSharingService.h.