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.