SwapKit

• About SwapKit
• Download It!
• Documentation
• API Reference
• Issues + Code + Help

SwapKit Support in ∞labs's Mover Application.

Mover is a file transfer application produced by ∞labs and available for iPhone, iPod touch and iPad with iPhone OS 3.0 and later (web site). It's meant to be used to send items from a user to another when both users are physically present at the same location, much like the "send via Bluetooth" feature present in many other phones.

Previously, Mover only obtained items to send through built-in Apple APIs. From Mover 3.1 on, SwapKit allows any app to send and receive items through Mover. Read this document to find out how.

Supported Features

(For more information on how SwapKit support has evolved between versions, please check out Summary of SwapKit Support in ∞labs's Mover.)

Mover comes in three variants — "Lite" (free), "Plus" (paid) and an open source version, which appear to the user as different applications (having separate bundle identifiers). SwapKit support is identical in all three versions, and apps can send and receive all kinds of items as specified below regardless of variant. This allows the user to 'circumvent' some limitations of the Lite version, where some of the item kinds described below are not usually available; this is intentional, and allows developers to send to Mover without having to worry about free/paid users. (Note however that some limitations remain regardless of how the item was added; for example, Lite users cannot send items via Bluetooth. These do not affect any SwapKit-mediated action, such as adding items to the table, or receiving them from Mover.)

In 3.1, only items that have built-in support in Mover can be sent and received. The item kinds available in 3.1 are as follows:

• Bookmarks (public.url).
• Text clippings (as NSString or NSData items sent with the public.utf8-plain-text type).
• Images (public.jpeg, public.tiff, com.compuserve.gif, public.png, com.microsoft.bmp, com.microsoft.ico).
• Contacts (with the nonstandard type net.infinite-labs.Slide.AddressBookPersonPropertyList; for more information on this type, see below).

Mover supports the default action (kILSwapDefaultAction) and an appropriate "prepare for transfer" one (kILSwapPrepareForTransferAction).

Due to internal issues and the current SwapKit up-to-RAM-size-items limitation, receiving and sending for video items is not supported in Mover 3.1, but may become available in future releases.

The above list of types is for informational purposes only; if you think you want to add sending and receiving support for an item, even if it's not of one of the above types, do so. SwapKit's query APIs and the send controller will pick up any future Mover update that expands its capabilities, and will make it available without having to update your app; additionally, if you use an appropriate common action for searching (like the aforementioned "prepare for transfer" one), you will pick up all appropriate apps, not just Mover variants.

How it Works

Mover implements SwapKit features in the following way:

• Receiving (as performed by Mover), that is, taking an item from your application and adding it to the Mover table, is performed by sending an item through SwapKit for the default or prepare-for-transfer actions. To add an object to the Mover table, just send it using any of the standard SwapKit APIs; for example:

  ILSwapItem* item = [ILSwapItem itemWithValue:(@"Hello, world! I'm a text clipping")
                                          type:(@"public.text")
                                          attributes:nil];
  [[ILSwapService sharedService]
                         sendItem:(item)
                        forAction:kILSwapPrepareForTransferAction
      toApplicationWithIdentifier:(@"net.infinitelabs.Mover")];
  

  Note that we're using the Mover bundle identifier above. However, this is not recommended: different variants of Mover have different bundle identifiers. Use of ILSwapSendController or the item send query APIs in ILSwapService (for example, -allApplicationRegistrationsForSendingItems:ofType:forAction:) is recommended, and allows you to support other data transfer apps alongside Mover.

  Mover will not save the item to Apple-provided libraries or applications; it is assumed that the original item is kept in your app's storage, and that the user can refer to your app to retrieve it again. If you need the item to be saved elsewhere, do so yourself using Apple APIs before sending the item to Mover.

• Sending (as performed by Mover), that is, getting an item transferred through Mover into your application, is implemented by your application exposing the default action for the types you are interested in. Mover 3.1 displays a "Send to App" button in the received item's actions menu (accessible by touching Edit, then the action button over an item) that uses ILSwapSendController to display a list of apps that can receive that object type.

  The screenshot below shows the "Send to App" button in the action menu.

Sending and Receiving Contacts

Mover 3.1 currently does not have a vCard parser; instead, it internally represents a contact as a property list containing the same information provided by the corresponding Address Book ABRecordRef object.

The SwapKit 1.0 distribution includes two files, ILSwapMvrContactSupport.h and ILSwapMvrContactSupport.m, that you can include in your project. These files implement a category on ILSwapItem that provides both receiving and sending support for contacts in the format, and a constant (kMvrContactAsPropertyListType) that you can use as the type of items produced by the category.

To use it, include the files in your project and link to AddressBook.framework; then:

ABRecordRef person = /* some record you want to send via Mover */;
ILSwapItem* item = [ILSwapItem moverContactItemFromPersonRecord:person];
[[ILSwapService sharedService]
                       sendItem:item
                         ofType:kMvrContactAsPropertyListType
                      forAction:kILSwapPrepareForTransferAction
    toApplicationWithIdentifier:(@"net.infinitelabs.Mover")];

Likewise, to copy a ABRecordRef corresponding to a contact sent by Mover, use the -copyPersonRecordFromMoverContactItem method in ILSwapItem introduced by the above files.