Selecting Applications and Documents

Users can select applications and documents to share audio/video content over iChat Theater. Users do this by choosing File > Share a File with iChat Theater and selecting an application or document to share. Or the user can drag an application icon directly into a video chat window. These actions start a session with the associated client application.

Applications and their documents do not automatically appear as choices to the user, unless iChat Theater knows they have audio/video sources that can be shared. Specifically, iChat Theater needs to know which applications for which types of documents can share audio/video. iChat Theater gets this information from the application’s information property list file. Therefore, edit your application’s information property list file as described in this article, to enable users to share your application and documents over iChat Theater.

There are two ways for applications to identify themselves as potential audio/video sources for iChat Theater. Document-based applications can register their document types using the LSCanProvideIMVideoDataSource Boolean key described in “Registering Document Types.” Applications that do not have documents but still provide audio/video sources can also use this key as described in “Registering Non-document Applications.”

In addition, the application needs to provide the audio/video source upon request by the user. Read “Sharing Audio/Video Content” for the steps you need to take when the user selects your application or its documents.

The information property list file, Info.plist, is located in the application’s bundle. Read Xcode 2 User Guide to learn more about the information property list.

Registering Document Types

To identify a document type supported by your application as a potential audio/video source for iChat Theater, add the LSCanProvideIMVideoDataSource Boolean key to the corresponding dictionary in the CFBundleDocumentTypes array in the application's Info.plist file. If you set LSCanProvideIMVideoDataSource to true, users can select that document type to share over iChat Theater. The default value is false.

For example, Listing 1 shows a fragment of an information property list that identifies all documents of type xyz as potential audio/video sources. This signifies that the application is capable of opening, viewing, and sharing over iChat Theater documents of type xyz.

Not all document types supported by an application need to be audio/video sources. Add the LSCanProvideIMVideoDataSource key, setting the value to true, only for those document types that can be audio/video sources.

Listing 1  Enabling a document-based application

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleDevelopmentRegion</key>
    <string>English</string>
    <key>CFBundleDocumentTypes</key>
    <array>
        <dict>
            <key>CFBundleTypeExtensions</key>
            <array>
                <string>xyz</string>
            </array>
            <key>CFBundleTypeIconFile</key>
            <string>KeyDocument</string>
            <key>CFBundleTypeName</key>
            <string>BGDocumentTypeShow</string>
            <key>CFBundleTypeRole</key>
            <string>Editor</string>
            <key>LSCanProvideIMVideoDataSource</key>
            <true/>
            <key>LSTypeIsPackage</key>
            <true/>
            <key>NSDocumentClass</key>
            <string>BGDocument</string>
        </dict>
        ...
    </array>
    ...
</dict>
</plist>

Registering Non-Document Applications

If an application doesn’t have any documents but nevertheless is capable of sharing audio/video content over iChat Theater, insert the LSCanProvideIMVideoDataSource Boolean key at the top level of the information property list.

For example, Listing 2 shows the information property list for an application called StarViewer that renders a view of the night sky. The information property list sets the LSCanProvideIMVideoDataSource key to true to allow users to select StarViewer from iChat Theater.

Listing 2  Enabling a non-document-based application

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleDevelopmentRegion</key>
    <string>English</string>
    <key>CFBundleExecutable</key>
    <string>StarViewer</string>
    <key>CFBundleGetInfoString</key>
    <string>1.0, Copyright 2007 My Company Inc.</string>
    <key>CFBundleIconFile</key>
    <string>StarViewer</string>
    <key>CFBundleIdentifier</key>
    <string>com.mycompany.StarViewer</string>
    <key>LSCanProvideIMVideoDataSource</key>
    <true/>
    <key>CFBundleInfoDictionaryVersion</key>
    <string>1.0</string>
    <key>CFBundleName</key>
    <string>StarViewer</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>CFBundleShortVersionString</key>
    <string>1.0</string>
    <key>CFBundleSignature</key>
    <string>star</string>
    <key>CFBundleVersion</key>
    <string>118</string>
    <key>LSMinimumSystemVersion</key>
    <string>10.5.0</string>
    <key>LSRequiresNativeExecution</key>
    <true/>
    <key>NSMainNibFile</key>
    <string>MainMenu</string>
    <key>NSPrincipalClass</key>
    <string>NSApplication</string>
</dict>
</plist>

Sharing Audio/Video Content

When an application or document is selected by the user to share over iChat Theater, the state of the associated application’s shared IMAVManager object changes to IMAVRequested. Applications should observe the IMAVManagerStateChangedNotification notification to handle this event.

To respond to the user request, document-based applications need to invoke the URLToShare method to get the selected file and start sharing its content. Note that iChat opens the document using Launch Services, so the application should not start the session until the document is finished loading.

Document-based applications should also observe the IMAVManagerURLToShareChangedNotification notification to be notified when the user selects another document to share. When this notification is sent, invoke the URLToShare method again to get the new file. Applications should just use the setVideoDataSource: method to change the content without stopping and starting the session.

Applications that do not have documents simply begin sharing their content when the state of the shared IMAVManager object changes to IMAVRequested.