com.voiceclearly.api
Class VoiceClearlyService

java.lang.Object
  com.voiceclearly.api.VoiceClearlyService

public class VoiceClearlyService
extends java.lang.Object

VoiceClearlyService is the main starting point for using the VoiceClearly Java api for Google Talk. The service exposes a simple api that allows you to create both voice and chat sessions with Google Talk users who are using either the Google Talk client or the GMail based chat application. Below is an example of creating a voice call to another Google Talk user in java

public class GoogleTalkClient implements CallListener{

public void incomingCall(Call call) {
System.out.println("incomingCall");
}

public void callAnswered(Call call) {
System.out.println("callAnswered");
}

public void callDeclined(Call call, String reason) {
System.out.println("callDeclined");
}

public void callDisconnected(Call call, String reason) {
System.out.println("callEnded");
}

public void incomingIm(Chat chat, Message message) {
System.out.println("incomingIm");
}

public static void main(String[] args)
{
//Class that implements CallListener to receive callback events.
GoogleTalkClient callBackListener = new GoogleTalkClient();

//Initialize the VoiceClearly Service with the listener
VoiceClearlyService service = new VoiceClearlyService(callBackListener);

//Login with Google Talk credentials
service.login("youremail@gmail.com", "yourpassword");

//Place call to another contact in your roster
service.placeCall("otheruser@gmail.com");
}
}



Constructor Summary

VoiceClearlyService(CallListener listener)
Class constructor that includes a CallListener so that clients can be notified of call events and take appropriate action.

VoiceClearlyService(java.lang.String gmailUsername, java.lang.String password, CallListener listener)
Class constructor that includes a CallListener so that clients can be notified of call events and take appropriate action.

Method Summary

Contact	addContact(Contact contact, boolean addToRoster) Adds a Google contact to the GMail account.
void	answerCall(Call call) Answers an incoming call, sets up appropriate media and triggers call event listeners.
Chat	createChatSession(java.lang.String gmailUsername) Triggered when an incoming chat session has started
void	deleteContact(Contact contact) Deletes a GMail contact.
Chat	getChatSession(java.lang.String gmailUsername) Retrieves a Chat given the GMail username.
java.util.ArrayList	getContacts() Returnes a list of GMail contacts using the Google gdata api.
Presence	getPresence(java.lang.String user) Retrieves the presence for the selected user
java.util.ArrayList	getRoster() Returns an ArrayList of Contacts in the roster with their current status.
void	hangup(Call call) Hangs up an active Google Talk voice call.
boolean	isLoggedIn() Helper method to determine if a user is logged in
boolean	login(java.lang.String gmailUsername, java.lang.String password) Logs user into the Google Talk service
boolean	login(java.lang.String gmailUsername, java.lang.String password, java.lang.String domain) Logs user in to the selected service domain, typically gmail.com
void	logout() Logs user out of the Google Talk service
Call	placeCall(java.lang.String gmailAddress) Place a Google Talk voice call to the seletect Google Talk address.
void	sendIM(java.lang.String gmailUsername, java.lang.String text) Sends an Google Talk Instant Message
void	setPresence(GooglePresence.Type type, GooglePresence.Mode mode)
void	setPresence(GooglePresence.Type type, java.lang.String customStatus, GooglePresence.Mode mode) Set the Google Talk Presence
Contact	updateContact(Contact contact) Update a GMail contact.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

VoiceClearlyService

public VoiceClearlyService(CallListener listener)

Class constructor that includes a CallListener so that clients can be notified of call events and take appropriate action.

Parameters:

listener - callback interface to receive call session event notifications

VoiceClearlyService

public VoiceClearlyService(java.lang.String gmailUsername,
                           java.lang.String password,
                           CallListener listener)

Class constructor that includes a CallListener so that clients can be notified of call events and take appropriate action.

Parameters:

gmailUsername - Google Username used for XMPP authentication. Can be just the username portion or the entire GMail email address.

password - Google Talk password

listener - callback interface to receive call session event notifications

Method Detail

login

public boolean login(java.lang.String gmailUsername,
                     java.lang.String password)

Logs user into the Google Talk service

Parameters:

gmailUsername - username to login with

password - password of the user logging in

Returns:

success boolean

logout

public void logout()

Logs user out of the Google Talk service

isLoggedIn

public boolean isLoggedIn()

Helper method to determine if a user is logged in

Returns:

login

public boolean login(java.lang.String gmailUsername,
                     java.lang.String password,
                     java.lang.String domain)

Logs user in to the selected service domain, typically gmail.com

Parameters:

gmailUsername - username to login with

password - user password

domain - domain of the user, typically gmail.com

Returns:

setPresence

public void setPresence(GooglePresence.Type type,
                        java.lang.String customStatus,
                        GooglePresence.Mode mode)

Set the Google Talk Presence

Parameters:

type - available, unavailable, etc messages representing status types

custom - Status text string for custom display message

mode - determines whether the user is busy or available

setPresence

public void setPresence(GooglePresence.Type type,
                        GooglePresence.Mode mode)

placeCall

public Call placeCall(java.lang.String gmailAddress)

Place a Google Talk voice call to the seletect Google Talk address. This entity must be in the current user's roster.

Parameters:

gmailAddress - - Google Talk address of the entity to call via Google Talk

answerCall

public void answerCall(Call call)

Answers an incoming call, sets up appropriate media and triggers call event listeners.

hangup

public void hangup(Call call)

Hangs up an active Google Talk voice call.

createChatSession

public Chat createChatSession(java.lang.String gmailUsername)

Triggered when an incoming chat session has started

Parameters:

gmailUsername - Google Talk address of the user with which the chat has been created.

Returns:

Chat

getChatSession

public Chat getChatSession(java.lang.String gmailUsername)

Retrieves a Chat given the GMail username. If no current chat exists, a new chat session is created.

Parameters:

gmailUsername - username used to get the Chat session

Returns:

Chat

sendIM

public void sendIM(java.lang.String gmailUsername,
                   java.lang.String text)

Sends an Google Talk Instant Message

Parameters:

gmailUsername - user to which the message is sent

text - message text

getPresence

public Presence getPresence(java.lang.String user)

Retrieves the presence for the selected user

Parameters:

user - presence for the selected user

Returns:

presence object

getRoster

public java.util.ArrayList getRoster()

Returns an ArrayList of Contacts in the roster with their current status.

Returns:

ArrayList Contacts in the roster.

getContacts

public java.util.ArrayList getContacts()

Returnes a list of GMail contacts using the Google gdata api.

Returns:

ArrayList GMail Contacts retrieved using the gdata api provided by Google. Uses the current logged in user to retrieve them.

addContact

public Contact addContact(Contact contact,
                          boolean addToRoster)

Adds a Google contact to the GMail account. If the addToRoster flag is true, this method also adds the new contact to the roster using the given email address and contact name.

Parameters:

contact - contact to add

inRoster - whether the user is already in the roster

Returns:

Contact newly created contact. Null if contact exists or if there is an error in processing.

updateContact

public Contact updateContact(Contact contact)

Update a GMail contact.

Parameters:

contact - Contact object previously retrieve using the service

Returns:

Contact contact updated

deleteContact

public void deleteContact(Contact contact)

Deletes a GMail contact.

Parameters:

contact - the contact to delete.