com.nokia.mid.voip
Interface VoipAudioCall


public interface VoipAudioCall

Represents an interface to one VoIP Audio Call.

Applications cannot instantiate VoIP Audio Call directly. Instead, VoipManager is used to obtain VoIP Audio Call instance. Each VoIP call has it's own instance. Each instance can control only the call that the instance is attached to.

Before application can use VoIP Audio Call services, it must first write its settings via VoipSettings class and listen state updates via VoipSettingsStateListener

 
import com.nokia.mid.voip.VoipManager; import com.nokia.mid.voip.VoipSettings; import com.nokia.mid.voip.VoipSettingsStateListener; import com.nokia.mid.voip.VoipStates; import com.nokia.mid.voip.VoipCauses; ... public void writeSettings( String xml_doc ){ VoipSettings mySettings = VoipManager.createVoipSettingsInstance(); // Create listener for settings VoipSettingsStateListener settingsListener = new VoipSettingsStateListener(){ public void voipSettingsUpdated( int state, int cause ) { switch(state) { case VoipStates.SETTINGS_ERROR: // Writing the settings failed settingsError( cause ); break; case VoipStates.SETTINGS_ONLINE: // Settings are online. Now we can create and receive calls! settingsOnline(); break; case VoipStates.SETTINGS_OFFLINE: // Settings are offline settingsOffline( cause ); break; } } }; // Set settings state listener mySettings.setVoipSettingsStateListener( settingsListener ); // Write our service provisioning settings to phone mySettings.writeVoipSettings( xml_doc );

When settings are online MIDlet can create and receive calls. If MIDlet is not running when MIDlet related VoIP account receives call, MIDlet will be startet using content handler API invocation. Launch reason and call id can be obtained from MIDlet application properties. arg-0 contains launch reason and arg-1 has call id. Launch reason strings are defined in VoipManager.

 
String launch_reason = getAppProperty("arg-0"); int call_id = Integer.parseInt(getAppProperty("arg-1"));

After obtaining a reference to a VoIP Audio Call using VoipManager, applications can use method startCall to initiate MO call or to answer ringing MT call.

 
import com.nokia.mid.voip.VoipManager; import com.nokia.mid.voip.VoipAudioCall; import com.nokia.mid.voip.VoipAudioCallStateListener; import com.nokia.mid.voip.VoipStates; import com.nokia.mid.voip.VoipCauses; ... public void make_call( int call_id ){ // Create call instance for incoming call VoipAudioCall call = VoipManager.createVoipAudioMTCallInstance( call_id ); // Create Call state listener VoipAudioCallStateListener callListener = new VoipAudioCallStateListener(){ public void voipAudioCallUpdated(int state, int cause, int callid){ if ( state == VoipStates.AUDIOCALL_CALL ){ callStateChanged(callid, cause); } if ( state == VoipStates.AUDIOCALL_ENDED ){ handleCallEnded(callid, cause); } if ( state == VoipStates.AUDIOCALL_NOTIF ){ handleCallNotifications(callid, cause); } if ( state == VoipStates.AUDIOCALL_OPERROR ){ handleOperationErrors(callid, cause); } } }; // Set call state listener call.setVoipAudioCallStateListener(callListener); // Get show caller id boolean show_caller_id = MyTestMidletSettingsContainer.isCallerIdEnabled(); // Everything should be ready, start call!! call.startCall(show_caller_id);


Method Summary
 boolean endCall()
          Ends VoIP Audio Call.
 java.lang.String getCallAddress()
          Get the address of the VoIP Audio Call.
 int getCallState()
          Return current call state
 boolean getSpeakerMode()
          Get call speaker mode
 void holdCall()
          Hold call
 boolean isMuted()
          Checks is the call muted
 boolean isOnHold()
          Checks is call held
 void retrieveCall()
          Retrieve held call
 void sendDTMF(java.lang.String dtmfString)
          Sends DTMF string
 void setSpeakerMode(boolean speakerMode)
          Set call speaker mode
 void setVoipAudioCallStateListener(VoipAudioCallStateListener callListener)
          Associates VoipAudioCallStateListener with the VoipAudioCall.
 boolean startCall(boolean showCallerId)
          Starts VoIP Audio Call
 void startDTMF(char digit)
          Send one DTMF digit
 void stopDTMF()
          Stop sending DTMF tone initiated by startDTMF
 void toggleMute()
          Toggles mute
 

Method Detail

startCall

boolean startCall(boolean showCallerId)

Starts VoIP Audio Call

If call is MT type calling this method answers the call. On MO calls this method starts calling recipient address.

In order to detect state changes of call states, the state listener should be set first via setVoipAudioCallStateListener.

Parameters:
showCallerId - true will show caller ID (CLIP), false restricts caller ID (CLIR). For MT calls this parameter is ignored.
Returns:
true if call can be started, false if call start fails
Throws:
java.lang.IllegalStateException - if call has already been started

endCall

boolean endCall()

Ends VoIP Audio Call.

This method is used for rejecting incoming call, disconnecting ringing and ending active call.

Returns:
false if current call is not active, incoming or waiting call

toggleMute

void toggleMute()

Toggles mute

Changes mute setting from muted to not muted and vice versa. Calling this is allowed for active call or if this is only call. As mute setting is common for all calls platform does not allow changing mute if there are other active calls. Note that phone could have other calls that are not MIDlet controlled.

When mute status changes platform sends VoipStates.AUDIOCALL_NOTIF event with cause VoipCauses.CAUSE_MUTE_CHANGED.

Throws:
java.lang.IllegalStateException - if call is not only call or current active call

isMuted

boolean isMuted()

Checks is the call muted

Mute setting is common for all calls. When other call is active it can change mute setting.

Returns:
true if call is muted, false if call is not muted

holdCall

void holdCall()

Hold call

This will set call associated with object as held. If there is another held call this will perform swap operation between calls.

Throws:
java.lang.IllegalStateException - if call is not current active call

retrieveCall

void retrieveCall()

Retrieve held call

Calling this will retrieve held call.

Throws:
java.lang.IllegalStateException - if call is not held call

isOnHold

boolean isOnHold()

Checks is call held

Returns:
true if call is held, false if call is not held

getCallState

int getCallState()

Return current call state

Returns:
Current call state as specified in VoipCauses

getCallAddress

java.lang.String getCallAddress()

Get the address of the VoIP Audio Call.

Returns remote party address. When AUDIOCALL_COLP event is received for outgoing calls, final address is available.

Returns:
URI associated with this call. If call is not yet initiated this method returns null.

startDTMF

void startDTMF(char digit)

Send one DTMF digit

Sends only one continuous DTMF digit. Valid characters for DTMF are 0 9, *, #, A-D and p. According to RFC 4733 characters 0-9 maps to decimal value 0-9, * to 10, # to 11 and A-D to 12-15.

Client must end sending by calling stopDTMF.

Parameters:
digit - DTMF digit
Throws:
java.lang.IllegalStateException - if call is not active

stopDTMF

void stopDTMF()

Stop sending DTMF tone initiated by startDTMF

This method does nothing if DTMF code is not being sent.

Throws:
java.lang.IllegalStateException - if call is not active

sendDTMF

void sendDTMF(java.lang.String dtmfString)

Sends DTMF string

Sends DTMF digits as a burst. Valid characters for DTMF string are 0 9, *, #, A-D and p. According to RFC 4733 characters 0-9 maps to decimal value 0-9, * to 10, # to 11 and A-D to 12-15. p character causes 1 second pause.

 An example:
 call.sendDTMF("*1956*p*45#AB");
 

When DTMF code is being transmitted AUDIOCALL_NOTIF event with cause CAUSE_DTMF_ACTIVE is sent to call state listener. When DTMF code is sent cause CAUSE_DTMF_IDLE is sent.

Parameters:
dtmfString - DTMF digits in one string.

setSpeakerMode

void setSpeakerMode(boolean speakerMode)

Set call speaker mode

Sets speaker mode for calls. Speaker mode can be set only if this call is only call or active call. As mute setting is common for all calls, platform does not allow changing speaker mode if there are other active VoIP calls. Note that phone could have other calls that are not MIDlet controlled.

When speaker status changes platform sends VoipStates.AUDIOCALL_NOTIF event with cause VoipCauses.CAUSE_SPEAKER_MODE_CHANGED.

Parameters:
speakerMode - true route audio to speaker, false route audio to earpiece. Calling with same speaker mode as current setting has no effect.
Throws:
java.lang.IllegalStateException - if current call is not only call or active call.

getSpeakerMode

boolean getSpeakerMode()

Get call speaker mode

Gets speaker mode for calls

Returns:
true when speaker is active, false for earpiece

setVoipAudioCallStateListener

void setVoipAudioCallStateListener(VoipAudioCallStateListener callListener)
Associates VoipAudioCallStateListener with the VoipAudioCall. The listener should be activated to listen needed state changes of the VoIP Audio Call. Setting a listener replaces any existing listener (i.e. only one listener can be registered to each VoipAudioCall instance). To remove the currently active listener, a null parameter must be given.

Parameters:
callListener - an instance of VoipAudioCallStateListener, or null to remove the currently-active listener.


Copyright © 2013 Nokia Corporation. All rights reserved.

Nokia is registered trademark of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Oracle Corporation. Other product and company names mentioned herein may be trademarks or trade names of their respective owners. This document is confidential information of Nokia Corporation.

Disclaimer
The information in this document is provided "as is," with no warranties whatsoever, including any warranty of merchantability, fitness for any particular purpose, or any warranty otherwise arising out of any proposal, specification, or sample. Furthermore, information provided in this document is preliminary, and may be changed substantially prior to final release.

Nokia Corporation disclaims all liability, including liability for infringement of any proprietary rights, relating to this document and implementation of any information presented in this document.

Nokia Corporation retains the right to make changes to this document at any time, without notice.

License
Subject to above disclaimer, a license is hereby granted to use this documentation solely under existing Limited License Agreement and non-disclosure agreement between the companies for the agreed application development for S40 Nokia phones. No other licenses e.g. to any intellectual property rights are granted herein. Any use of the screen shots of this documentation, including any icons thereof, is subject to Nokia's prior written approval.