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.
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.
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
VARIANT s, 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.
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:
- 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:
- 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.
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 the
IGoogleDesktopPluginTalkHandler
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.
|