Google Desktop
 Google Desktop Sidebar Communication API

For Users
  Download Plug-ins
  Desktop Search Forum

For Developers
  Plug-in Development
  Download SDK
  Developer Guide
    Index API
    Query API
    Display API
      Script API
      Communication API
      Plug-in Design Guidelines
      Plug-in Tutorials
        Using Wizard
        Using Helper Framework
        Using ActiveX
    Action API
    Event API
    Plug-in Installer
  Submit Software
  Developer Forum
  Desktop Blog

Contents


Introduction

Sidebar plug-ins can now communicate with Sidebar plug-ins running on other machines, under the following conditions:

  • The plug-ins must be the same; a Tic-Tac-Toe plug-in can communicate with another Tic-Tac-Toe plug-in, but it can't communicate with a Scratch Pad plug-in or vice versa.
  • All users of the communicating plug-ins must be logged into Google Talk.

Google Talk serves as the communication medium for Sidebar plug-ins. If a user is logged into Google Talk, a plug-in can get a list of which of the user's Google Talk friends are currently online. Once it has the list of online friends, a plug-in can send and receive data from the same plug-in running on an online friend's machine. If a friend doesn't have Sidebar installed, a plug-in can instead send a text message to that friend.

The Communication API is available for both native and script-based plug-ins. This document only covers how to use the Communication API to add communication capabilities as part of a Sidebar plug-in. It assumes that you are familiar with the concepts and requirements for writing a Sidebar plug-in as described in either the Display API or Script API documents, depending on which you use to write your Sidebar plug-ins.

Back to top

Script Plug-ins

When adding communication capability to a script-based plug-in, you will use the global variable googleTalk both to send data and to set the handler function called when the plug-in receives data.

Your first step when sending data is to reference googleTalk's friends property, which gets an array of friend objects consisting of your online Google Talk friends.

A friend object has five properties:

  • name: Visible name in Google Talk.
  • user_id: Google Talk user id, passed as the data/message recipient parameter to the data/message sending methods.
  • email_address: Friend's email address.
  • has_sidebar: Boolean indicator if the friend has Sidebar installed. This should be checked before trying to send data to a possibly non-existant Sidebar.
  • status: Friend's Google Talk status, either online, idle, or busy, represented here as 0, 1, or 2 respectively.

Once the script has the array of your Google Talk friends, it sends data to them using one of two methods:

  • SendTalkData(friend_id, data): Sends the data string (maximum length 2K characters) to the friend identified by friend_id's Sidebar. Specifically, to the same panel in the friend's Sidebar as the method call is made from.
  • SendTalkText(friend_id, message): Sends an up to 2K character text message to the Google Talk user with friend_id. This method is usually used when the friend doesn't have Sidebar installed.

In order to receive data, you need to associate a function to handle it with googleTalk's onReceiveTalkData function handler. Your function's signature should be name(friend_object, data_string). This function will be called whenever your plug-in receives data, so you must write it so that it can deal with any and all messages another plug-in might send.

See the Script Plug-ins documentation for more information as well as the Tic-Tac-Toe example code included in the SDK.

Back to top

Native Plug-ins

The Desktop API has several plug-in communication-specific interfaces. In addition, some functions associated with more general Desktop API interfaces are used in plug-in communication.


Finding Friends and Sending Data

Your communication API starting point is the IGoogleDesktopPluginTalkService interface. Its methods get the list of the user's online Google Talk friends and send data to other plug-ins.

interface IGoogleDesktopPluginTalkService: IDispatch

  • get_friends: Get the user's online Google Talk friends.
    • Arguments:
      • [out] VARIANT* friends: a SAFEARRAY of VARIANTs, each holding an IGoogleDesktopTalkFriend object
    • Returns:
      • S_OK if successful.
      • Appropriate error on failure.
  • SendTalkData: Sends up to a 2K character string to the same plug-in on a friend's machine.
    • Arguments:
      • BSTR user_id: the friend's user id to which Desktop sends the data.
      • BSTR data: the data string sent to the user.
    • Returns:
      • S_OK if successful.
      • Appropriate error on failure.
  • SendTalkText: Sends an up to 2K character text message to a user.
    • Arguments:
      • BSTR user_id: the friend's user id to which Desktop sends the message.
      • BSTR message: the IM text sent to the user.
    • Returns:
      • S_OK if successful.
      • Appropriate error on failure.

Before sending data, a plug-in should check if the recipient has Sidebar installed. Remember, the friends method returns online Google Talk friends, who may or may not be Sidebar users. SendTalkData sends data to Sidebar plug-ins, so it shouldn't be used if a friend doesn't have the Sidebar installed. SendTalkText sends an IM via Google Talk, and so will work for anyone on the Google Talk friends list. The IGoogleDesktopTalkFriend objects returned by the get_friends method contain a has_sidebar field that lets you check if a particular friend has Sidebar installed.

Back to top

Friend Objects

When your plug-in gets the list of friends, each friend is represented by a IGoogleDesktopTalkFriend object, which can have the following Google Talk status values.

enum GoogleDesktopTalkFriendStatus {
  GDD_FRIEND_STATUS_ONLINE = 0,
  GDD_FRIEND_STATUS_IDLE,
  GDD_FRIEND_STATUS_BUSY,
};

interface IGoogleDesktopTalkFriend: IDispatch

  • get_name: Gets the friend's user visible name.
    • Arguments:
      • [out] BSTR *name
    • Returns:
      • S_OK if successful.
      • Appropriate error on failure.
  • get_user_id: Gets the friend's userid, which you will pass to SendTalkText and SendTalkData.
    • Arguments:
      • [out] BSTR *user_id
    • Returns:
      • S_OK if successful.
      • Appropriate error on failure.
  • get_has_sidebar: Does the friend have Sidebar installed?.
    • Arguments:
      • [out] VARIANT_BOOL *installed
    • Returns:
      • S_OK if successful.
      • Appropriate error on failure.
  • get_status: The friend's Google Talk status (online, idle, busy; see GoogleDesktopTalkFriendStatus values above).
    • Arguments:
      • [out] GoogleDesktopTalkFriendStatus *status
    • Returns:
      • S_OK if successful.
      • Appropriate error on failure.
Back to top

Receiving Data

Now that you know how to find out who's available and how to send data to them, the next step is to add code to your plug-in that notifies it when data arrives. There are two ways to do this:

  • If your plug-in uses IGoogleDesktopDisplayPluginHelper, then you must also implement the IGoogleDesktopDisplayPluginHelper2 interface.
    • This allows you to override the sent/received data when a content item is sent to a friend. This is needed in case you want to serialize extra data associated with each content item, which the plug-in helper doesn't have access to.
  • Otherwise, you need to implement theIGoogleDesktopPluginTalkHandler interface.

interface IGoogleDesktopPluginTalkHandler: IUnknown

  • OnReceiveTalkMessage: Callback when a message arrives for your plug-in
    • Arguments:
      • IDispatch *talk_friend: the message sender, represented as an IGoogleDesktopTalkFriend.
      • BSTR data: the data. [tyg: Is this the message content, meta-data, or both?]
    • Returns:
      • S_OK if successful.
      • Appropriate error on failure.

interface IGoogleDesktopDisplayPluginHandler2: IUnknown

  • GetItemData: When you share a content item (i.e. a user right clicks the "Send to" menu item or drags and drops the item), this function serializes the item. The data goes to your friend's machine's OnReceiveTalkMessage handler. If you're using the content item helper, you can return E_NOTIMPL and let the plug-in helper handle the item.
    • Arguments:
      • IUnknown *item: the IGoogleDesktopDisplayContentItem to serialize.
      • [out] BSTR *data: store here whatever data you need to show the item in another Sidebar.
    • Returns:
      • S_OK if successful.
      • Appropriate error on failure.
  • GetItemText: When you share a content item with a user who doesn't have the Sidebar, you can instead send a text version of the item. If you're using the content item helper, then you can return E_NOTIMPL and let the plug-in helper handle the item.
    • Arguments:
      • IUnknown *item: the IGoogleDesktopDisplayContentItem to serialize.
      • [out] BSTR *message: the text of the instant message.
    • Returns:
      • S_OK if successful.
      • Appropriate error on failure.
  • OnReceiveTalkMessage: Callback for when a message arrives for your plug-in. If you use the content item helper, then you can return E_NOTIMPL and let the plug-in helper handle the item.
    • Arguments:
      • IDispatch *talk_friend: the message sender represented as an IGoogleDesktopTalkFriend.
      • BSTR data: the data.
    • Returns:
      • S_OK if successful.
      • Appropriate error on failure.

Finally, if your plug-in uses the IGoogleDesktopDisplayDetailsViewHelper , you should also implement IGoogleDesktopDisplayDetailsViewHandler2 . This notifies your plug-in when a user sends an item using the button in the details view.

enum GoogleDesktopSendToType {
  GDD_SEND_TO_SIDEBAR = 0,
  GDD_SEND_TO_IM,
  GDD_SEND_TO_EMAIL,
};

interface IGoogleDesktopDisplayDetailsViewHelper2: IUnknown

  • SendItemToFriend: Called when the user uses the send-to button in the Details view to send this item to a Google Talk friend.
    • Arguments:
      • IGoogleDesktopTalkFriend *talk_friend : the recipient of the item, represented as an IGoogleDesktopTalkFriend.
      • GoogleDesktopSendToType type: how the item is sent (see above for the enumeration of the three options).
    • Returns:
      • S_OK if successful.
      • Appropriate error on failure.

Back to top