googleTalk and friend

(Windows only)

The googleTalk object lets desktop gadgets communicate with desktop gadgets running on other machines, under the following conditions:

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

Google Talk serves as the communication medium for desktop gadgets. If a user is logged into Google Talk, a gadget 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 gadget can send and receive data from the same gadget running on an online friend's machine. If a friend doesn't have Google Desktop installed, a gadget can instead send a regular instant message to that friend.

Contents

• Using the googleTalk Object
• Security Considerations
• API Reference
  • googleTalk
  • friend

Using the googleTalk Object

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

Your first step when sending data is to reference googleTalk's friends property, which gets a list 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 Google Desktop installed. This should be checked before trying to send data to a possibly non-existent installation of Google Desktop.
• status: Friend's Google Talk status — gddFriendStatusOnline, gddFriendStatusIdle, or gddFriendStatusBusy.

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

• sendTalkData(friend_id, data): Sends the data string (maximum length 2K characters) to the friend identified by friend_id's installation of Google Desktop. Specifically, to the same gadget in the friend's Google Desktop as the method call is made from.
• sendTalkDataEx(friend_id, data, flags): Similar to sendTalkData except that a flag can be specified for how the message should behave while being sent/received. If silent, no message boxes will be displayed if the user doesn't have the plugin installed or active. The flag values are gddSendDataFlagNone and gddSendDataFlagSilent. Requires Google Desktop 4 or higher.
• sendTalkText(friend_id, message): Sends an up to 2K character instant message to the Google Talk user with friend_id. This method is usually used when the friend doesn't have Google Desktop installed.

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 gadget receives data, so you must write it so that it can deal with any and all messages another gadget might send.

See Creating a Gadget for more information as well as the TalkCommunication example (online and in the SDK).

Back to top

Security Considerations

Gadgets that use this API should not execute received data (for example, by calling eval()). Executing received data is a problem because a malicious user could modify the gadget to send script that executes on a friend's machine. The received script would run under local privileges and hence have access to local files and resources. To guard against this, eval() calls are checked to make sure that they are not evaluating received data.

Back to top

API Reference

• googleTalk
• Friend

googleTalk

(Windows only)

Properties

Name	Description	Type	Read/Write
friends	The friends that are online. To convert the list into an array, use code like this: googleTalk.friends.toArray(). If friends is empty (toArray returns a 0-length array) and talk_status shows that Google Talk is connected, then the user has no friends.	A list of friend objects.	Read only
talk_status (added 5.0)	The status of Google Talk on this machine. Possible values: gddTalkStatusNotRunning (Google Talk is not running; maybe it's not installed), gddTalkStatusDisconnected (Google Talk is running but disconnected; there might be no Internet connection), or gddTalkStatusConnected (Google Talk is running and connected).	integer	Read only

Methods

Name and Arguments	Description	Returns
sendTalkData(friend_id, data)	Sends a string to a friend. friend_id is from the user_id property of friend object.	Returns nothing.
sendTalkDataEx(friend_id, data, flags) (added 5.0)	Similar to sendTalkData, but you can specify a flag for how the message should behave while being sent/received. If silent, no message boxes will be displayed if the user doesn't have the plugin installed or active. Possible flag values: gddSendDataFlagNone, gddSendDataFlagSilent. Requires Google Desktop 4 or higher.	Returns nothing.
sendTalkText(friend_id, message)	Sends a message to a friend as an IM. friend_id is from the user_id property of friend object.	Returns nothing.

Event Handlers

Name	Prototype	Description	Returns
onReceiveTalkData	onReceiveTalkData(friend, data)	Called when the same plugin on a friend's machine sends data to you. friend is a friend object, and data is a string.	Returns nothing.

Friend

(Windows only)

This object is returned by googleTalk. Google Gadgets cannot create variables of this type.

Properties

Name	Description	Type	Read/Write
name	The friend's user visible name.	string	Read only
user_id	The friend's user id, this is passed as a parameter to methods such as sendTalkText and sendTalkData.	string	Read only
email_address	The friend's email address.	string	Read only
has_sidebar	Whether the friend has Google Desktop installed.	boolean	Read only
status	The Google Talk status of the friend (online/idle/busy).	integer	Read only