+ * For example, a remote request to have this party put off hold cannot + * override an earlier local request to put the remote party on hold. + *
+ * + * @param on true to request the media of this + * CallSession be put on hold; false, + * otherwise + * @param here true if the request comes from this side of the + * call; false if the remote party is the issuer of + * the request i.e. it's the result of a remote offer + */ + public void putOnHold(boolean on, boolean here) + { + if (on) + { + onHold |= (here ? ON_HOLD_LOCALLY : ON_HOLD_REMOTELY); + } + else + { + onHold &= ~ (here ? ON_HOLD_LOCALLY : ON_HOLD_REMOTELY); + } + + /* Put the send on/off hold. */ + boolean sendOnHold = + (0 != (onHold & (ON_HOLD_LOCALLY | ON_HOLD_REMOTELY))); + putOnHold(getAudioRtpManager(), sendOnHold); + putOnHold(getVideoRtpManager(), sendOnHold); + + /* Put the receive on/off hold. */ + boolean receiveOnHold = (0 != (onHold & ON_HOLD_LOCALLY)); + for (Iterator playerIter = players.iterator(); playerIter.hasNext();) + { + Player player = (Player) playerIter.next(); + + if (receiveOnHold) + player.stop(); + else + player.start(); + } + } + + /** + * Puts a the SendSteams of a specific RTPManager + * on/off hold i.e. stops/starts them. + * + * @param rtpManager the RTPManager to have its + * SendStreams on/off hold i.e. stopped/started + * @param on true to have the SendStreams of + * rtpManager put on hold i.e. stopped; false, + * otherwise + */ + private void putOnHold(RTPManager rtpManager, boolean on) + { + for (Iterator sendStreamIter = rtpManager.getSendStreams().iterator(); sendStreamIter + .hasNext();) + { + SendStream sendStream = (SendStream) sendStreamIter.next(); + + if (on) + { + try + { + sendStream.getDataSource().stop(); + sendStream.stop(); + } + catch (IOException ex) + { + logger.warn("Failed to stop SendStream.", ex); + } + } + else + { + try + { + sendStream.getDataSource().start(); + sendStream.start(); + } + catch (IOException ex) + { + logger.warn("Failed to start SendStream.", ex); + } + } + } + } + /** * The method is meant for use by protocol service implementations upon * reception of an SDP answer in response to an offer sent by us earlier. @@ -916,7 +1247,15 @@ private SessionDescription createSessionDescription( } } - allocateMediaPorts(intendedDestination); + /* + * For example, issuing a Request.INVITE for putting a + * CallParticipant on hold also needs a SessionDescrption. However, + * it just wants to describe the current state. + */ + if ((audioSessionAddress == null) || (videoSessionAddress == null)) + { + allocateMediaPorts(intendedDestination); + } InetAddress publicIpAddress = audioPublicAddress.getAddress(); @@ -1087,12 +1426,15 @@ private Vector createMediaDescriptions( , 1 , "RTP/AVP" , supportedAudioEncodings); + byte onHold = this.onHold; if (!mediaServCallback.getDeviceConfiguration() .isAudioCaptureSupported()) { - am.setAttribute("recvonly", null); + /* We don't have anything to send. */ + onHold |= ON_HOLD_REMOTELY; } + setAttributeOnHold(am, onHold); mediaDescs.add(am); } //--------Video media description @@ -1106,12 +1448,15 @@ private Vector createMediaDescriptions( , 1 , "RTP/AVP" , supportedVideoEncodings); + byte onHold = this.onHold; if (!mediaServCallback.getDeviceConfiguration() .isVideoCaptureSupported()) { - vm.setAttribute("recvonly", null); + /* We don't have anything to send. */ + onHold |= ON_HOLD_REMOTELY; } + setAttributeOnHold(vm, onHold); mediaDescs.add(vm); } @@ -1123,6 +1468,36 @@ private Vector createMediaDescriptions( return mediaDescs; } + /** + * Sets the call-hold related attribute of a specific + * MediaDescription to a specific value depending on the type of + * hold this CallSession is currently in. + * + * @param mediaDescription the MediaDescription to set the + * call-hold related attribute of + * @param onHold the call-hold state of this CallSession which is + * a combination of {@link #ON_HOLD_LOCALLY} and + * {@link #ON_HOLD_REMOTELY} + * @throws SdpException + */ + private void setAttributeOnHold(MediaDescription mediaDescription, + byte onHold) throws SdpException + { + String attribute; + + if (ON_HOLD_LOCALLY == (onHold | ON_HOLD_LOCALLY)) + attribute = + (ON_HOLD_REMOTELY == (onHold | ON_HOLD_REMOTELY)) ? "inactive" + : "sendonly"; + else + attribute = + (ON_HOLD_REMOTELY == (onHold | ON_HOLD_REMOTELY)) ? "recvonly" + : null; + + if (attribute != null) + mediaDescription.setAttribute(attribute, null); + } + /** * Compares audio/video encodings in the offeredEncodings * hashtable with those supported by the currently valid media controller diff --git a/src/net/java/sip/communicator/impl/protocol/sip/OperationSetBasicTelephonySipImpl.java b/src/net/java/sip/communicator/impl/protocol/sip/OperationSetBasicTelephonySipImpl.java index 59d9108dd..9dd24ba27 100644 --- a/src/net/java/sip/communicator/impl/protocol/sip/OperationSetBasicTelephonySipImpl.java +++ b/src/net/java/sip/communicator/impl/protocol/sip/OperationSetBasicTelephonySipImpl.java @@ -24,6 +24,7 @@ * implementing OperationSetBasicTelephony. * * @author Emil Ivov + * @author Lubomir Marinov */ public class OperationSetBasicTelephonySipImpl implements OperationSetBasicTelephony @@ -355,22 +356,182 @@ public Iterator getActiveCalls() /** * Resumes communication with a call participant previously put on hold. - * + * * @param participant the call participant to put on hold. + * @throws OperationFailedException */ public synchronized void putOffHold(CallParticipant participant) + throws OperationFailedException { - /** @todo implement putOffHold() */ + putOnHold(participant, false); } /** * Puts the specified CallParticipant "on hold". - * + * * @param participant the participant that we'd like to put on hold. + * @throws OperationFailedException */ public synchronized void putOnHold(CallParticipant participant) + throws OperationFailedException + { + putOnHold(participant, true); + } + + /** + * Puts the specified CallParticipant on or off hold. + * + * @param participant the CallParticipant to be put on or off hold + * @param on true to have the specified CallParticipant + * put on hold; false, otherwise + * @throws OperationFailedException + */ + private void putOnHold(CallParticipant participant, boolean on) + throws OperationFailedException + { + CallSession callSession = + ((CallSipImpl) participant.getCall()).getMediaCallSession(); + CallParticipantSipImpl sipParticipant = + (CallParticipantSipImpl) participant; + + try + { + sendInviteRequest(sipParticipant, callSession + .createSdpDescriptionForHold( + sipParticipant.getSdpDescription(), on)); + } + catch (MediaException ex) + { + throwOperationFailedException( + "Failed to create SDP offer to hold.", + OperationFailedException.INTERNAL_ERROR, ex); + } + + /* + * Putting on hold isn't a negotiation (i.e. the issuing side takes the + * decision and executes it) so we're muting now regardless of the + * desire of the participant to accept the offer. + */ + callSession.putOnHold(on, true); + + CallParticipantState state = sipParticipant.getState(); + if (CallParticipantState.ON_HOLD_LOCALLY.equals(state)) + { + if (!on) + sipParticipant.setState(CallParticipantState.CONNECTED); + } + else if (CallParticipantState.ON_HOLD_MUTUALLY.equals(state)) + { + if (!on) + sipParticipant.setState(CallParticipantState.ON_HOLD_REMOTELY); + } + else if (CallParticipantState.ON_HOLD_REMOTELY.equals(state)) + { + if (on) + sipParticipant.setState(CallParticipantState.ON_HOLD_MUTUALLY); + } + else if (on) + { + sipParticipant.setState(CallParticipantState.ON_HOLD_LOCALLY); + } + } + + /** + * Sends an invite request with a specific SDP offer (description) within + * the current Dialog with a specific call participant. + * + * @param sipParticipant the SIP-specific call participant to send the + * invite to within the current Dialog + * @param sdpOffer the description of the SDP offer to be made to the + * specified call participant with the sent invite + * @throws OperationFailedException + */ + private void sendInviteRequest(CallParticipantSipImpl sipParticipant, + String sdpOffer) throws OperationFailedException + { + Dialog dialog = sipParticipant.getDialog(); + Request invite = null; + try + { + invite = dialog.createRequest(Request.INVITE); + } + catch (SipException ex) + { + throwOperationFailedException("Failed to create invite request.", + OperationFailedException.INTERNAL_ERROR, ex); + } + + /* + * The authorization-related headers are the responsibility of the + * application (according to the Javadoc of JAIN-SIP). + */ + AuthorizationHeader authorization = + protocolProvider.getSipSecurityManager() + .getCachedAuthorizationHeader( + ((CallIdHeader) invite.getHeader(CallIdHeader.NAME)) + .getCallId()); + if (authorization != null) + { + invite.setHeader(authorization); + } + + try + { + invite.setContent(sdpOffer, protocolProvider.getHeaderFactory() + .createContentTypeHeader("application", "sdp")); + } + catch (ParseException ex) + { + throwOperationFailedException( + "Failed to parse SDP offer for the new invite.", + OperationFailedException.INTERNAL_ERROR, ex); + } + + ClientTransaction clientTransaction = null; + try + { + clientTransaction = + sipParticipant.getJainSipProvider().getNewClientTransaction( + invite); + } + catch (TransactionUnavailableException ex) + { + throwOperationFailedException( + "Failed to create a client transaction for the new invite.", + OperationFailedException.INTERNAL_ERROR, ex); + } + + try + { + dialog.sendRequest(clientTransaction); + } + catch (SipException ex) + { + throwOperationFailedException("Failed to send the new invite.", + OperationFailedException.NETWORK_FAILURE, ex); + } + } + + /** + * Logs a specific message and associated Throwable cause as an + * error using the current Logger and then throws a new + * OperationFailedException with the message, a specific error + * code and the cause. + * + * @param message the message to be logged and then wrapped in a new + * OperationFailedException + * @param errorCode the error code to be assigned to the new + * OperationFailedException + * @param cause the Throwable that has caused the necessity to + * log an error and have a new OperationFailedException + * thrown + * @throws OperationFailedException + */ + private void throwOperationFailedException(String message, int errorCode, + Throwable cause) throws OperationFailedException { - /** @todo implement putOnHold() */ + logger.error(message, cause); + throw new OperationFailedException(message, errorCode, cause); } /** @@ -432,16 +593,19 @@ public void processRequest(RequestEvent requestEvent) if (request.getMethod().equals(Request.INVITE)) { logger.debug("received INVITE"); - if (serverTransaction.getDialog().getState() == null) + DialogState dialogState = serverTransaction.getDialog().getState(); + if ((dialogState == null) + || dialogState.equals(DialogState.CONFIRMED)) { if (logger.isDebugEnabled()) logger.debug("request is an INVITE. Dialog state=" - + serverTransaction.getDialog().getState()); + + dialogState); processInvite(jainSipProvider, serverTransaction, request); } else { - logger.error("reINVITE-s are not currently supported."); + logger + .error("reINVITEs while the dialog is not confirmed are not currently supported."); } } //ACK @@ -572,8 +736,11 @@ private void processTrying(ClientTransaction clientTransaction, return; } - //change status - callParticipant.setState(CallParticipantState.CONNECTING); + // change status + CallParticipantState callParticipantState = callParticipant.getState(); + if (!CallParticipantState.CONNECTED.equals(callParticipantState) + && !CallParticipantState.isOnHold(callParticipantState)) + callParticipant.setState(CallParticipantState.CONNECTING); } /** @@ -677,15 +844,11 @@ private void processInviteOK(ClientTransaction clientTransaction, return; } } - - if (callParticipant.getState() == CallParticipantState.CONNECTED) - { - // This can happen if the OK UDP packet has been resent due to a - //timeout. (fix by Michael Koch) - logger.debug("Ignoring invite OK since call participant is " - +"already connected."); - return; - } + + /* + * Receiving an Invite OK is allowed even when the participant is + * already connected for the purposes of call hold. + */ Request ack = null; ContentTypeHeader contentTypeHeader = null; @@ -777,9 +940,13 @@ private void processInviteOK(ClientTransaction clientTransaction, return; } } - - callSession.processSdpAnswer(callParticipant - , callParticipant.getSdpDescription()); + CallParticipantState callParticipantState = callParticipant.getState(); + if ((callParticipantState != CallParticipantState.CONNECTED) + && !CallParticipantState.isOnHold(callParticipantState)) + { + callSession.processSdpAnswer(callParticipant, callParticipant + .getSdpDescription()); + } //set the call url in case there was one /** @todo this should be done in CallSession, once we move * it here.*/ @@ -812,8 +979,9 @@ private void processInviteOK(ClientTransaction clientTransaction, + exc.getMessage()); } - //change status - callParticipant.setState(CallParticipantState.CONNECTED); + // change status + if (!CallParticipantState.isOnHold(callParticipant.getState())) + callParticipant.setState(CallParticipantState.CONNECTED); } /** @@ -1166,12 +1334,21 @@ private void processInvite( SipProvider sourceProvider, ServerTransaction serverTransaction, Request invite) { - logger.trace("Creating call participant."); Dialog dialog = serverTransaction.getDialog(); - CallParticipantSipImpl callParticipant - = createCallParticipantFor(serverTransaction, sourceProvider); - logger.trace("call participant created = " + callParticipant); + CallParticipantSipImpl callParticipant = + activeCallsRepository.findCallParticipant(dialog); + int statusCode; + if (callParticipant == null) + { + statusCode = Response.RINGING; + logger.trace("Creating call participant."); + callParticipant = + createCallParticipantFor(serverTransaction, sourceProvider); + logger.trace("call participant created = " + callParticipant); + } + else + statusCode = Response.OK; //sdp description may be in acks - bug report Laurent Michel ContentLengthHeader cl = invite.getContentLength(); @@ -1241,21 +1418,38 @@ private void processInvite( SipProvider sourceProvider, } } - //Send RINGING - logger.debug("Invite seems ok, we'll say RINGING."); - Response ringing = null; + // Send statusCode + String statusCodeString = + (statusCode == Response.RINGING) ? "RINGING" : "OK"; + logger.debug("Invite seems ok, we'll say " + statusCodeString + "."); + Response response = null; try { - ringing = protocolProvider.getMessageFactory().createResponse( - Response.RINGING, invite); - protocolProvider.attachToTag(ringing, dialog); - ringing.setHeader(protocolProvider.getSipCommUserAgentHeader()); + response = protocolProvider.getMessageFactory().createResponse( + statusCode, invite); + protocolProvider.attachToTag(response, dialog); + response.setHeader(protocolProvider.getSipCommUserAgentHeader()); //set our display name - ((ToHeader)ringing.getHeader(ToHeader.NAME)) + ((ToHeader)response.getHeader(ToHeader.NAME)) .getAddress().setDisplayName(protocolProvider .getOurDisplayName()); - ringing.addHeader(protocolProvider.getContactHeader()); + response.addHeader(protocolProvider.getContactHeader()); + + if (statusCode != Response.RINGING) + { + try + { + processInviteSendingResponse(callParticipant, response); + } + catch (OperationFailedException ex) + { + logger.error("Error while trying to send a request", ex); + callParticipant.setState(CallParticipantState.FAILED, + "Internal Error: " + ex.getMessage()); + return; + } + } } catch (ParseException ex) { logger.error("Error while trying to send a request" @@ -1265,9 +1459,10 @@ private void processInvite( SipProvider sourceProvider, return; } try { - logger.trace("will send ringing response: "); - serverTransaction.sendResponse(ringing); - logger.debug("sent a ringing response: " + ringing); + logger.trace("will send " + statusCodeString + " response: "); + serverTransaction.sendResponse(response); + logger + .debug("sent a " + statusCodeString + " response: " + response); } catch (Exception ex) { logger.error("Error while trying to send a request" @@ -1277,6 +1472,127 @@ private void processInvite( SipProvider sourceProvider, , "Internal Error: " + ex.getMessage()); return; } + + if (statusCode != Response.RINGING) + { + try + { + processInviteSentResponse(callParticipant, response); + } + catch (OperationFailedException ex) + { + logger.error("Error after sending a request", ex); + } + } + } + + /** + * Provides a hook for this instance to take last configuration steps on a + * specific Response before it is sent to a specific + * CallParticipant as part of the execution of + * {@link #processInvite(SipProvider, ServerTransaction, Request)}. + * + * @param participant the CallParticipant to receive a specific + * Response + * @param response the Response to be sent to the + * participant + * @throws OperationFailedException + * @throws ParseException + */ + private void processInviteSendingResponse(CallParticipant participant, + Response response) throws OperationFailedException, ParseException + { + /* + * At the time of this writing, we're only getting called because a + * response to a call-hold invite is to be sent. + */ + + CallSession callSession = + ((CallSipImpl) participant.getCall()).getMediaCallSession(); + CallParticipantSipImpl sipParticipant = + (CallParticipantSipImpl) participant; + String sdpOffer = sipParticipant.getSdpDescription(); + + String sdpAnswer = null; + try + { + sdpAnswer = + callSession.createSdpDescriptionForHold(sdpOffer, callSession + .isSdpOfferToHold(sdpOffer)); + } + catch (MediaException ex) + { + throwOperationFailedException( + "Failed to create SDP answer to put-on/off-hold request.", + OperationFailedException.INTERNAL_ERROR, ex); + } + + response.setContent(sdpAnswer, protocolProvider.getHeaderFactory() + .createContentTypeHeader("application", "sdp")); + } + + /** + * Provides a hook for this instance to take immediate steps after a + * specific Response has been sent to a specific + * CallParticipant as part of the execution of + * {@link #processInvite(SipProvider, ServerTransaction, Request)}. + * + * @param participant the CallParticipant who was sent a specific + * Response + * @param response the Response that has just been sent to the + * participant + * @throws OperationFailedException + * @throws ParseException + */ + private void processInviteSentResponse(CallParticipant participant, + Response response) throws OperationFailedException + { + /* + * At the time of this writing, we're only getting called because a + * response to a call-hold invite is to be sent. + */ + + CallSession callSession = + ((CallSipImpl) participant.getCall()).getMediaCallSession(); + CallParticipantSipImpl sipParticipant = + (CallParticipantSipImpl) participant; + + boolean on = false; + try + { + on = + callSession + .isSdpOfferToHold(sipParticipant.getSdpDescription()); + } + catch (MediaException ex) + { + throwOperationFailedException( + "Failed to create SDP answer to put-on/off-hold request.", + OperationFailedException.INTERNAL_ERROR, ex); + } + + callSession.putOnHold(on, false); + + CallParticipantState state = sipParticipant.getState(); + if (CallParticipantState.ON_HOLD_LOCALLY.equals(state)) + { + if (on) + sipParticipant.setState(CallParticipantState.ON_HOLD_MUTUALLY); + } + else if (CallParticipantState.ON_HOLD_MUTUALLY.equals(state)) + { + if (!on) + sipParticipant.setState(CallParticipantState.ON_HOLD_LOCALLY); + } + else if (CallParticipantState.ON_HOLD_REMOTELY.equals(state)) + { + if (!on) + sipParticipant.setState(CallParticipantState.CONNECTED); + } + else if (on) + { + sipParticipant.setState(CallParticipantState.ON_HOLD_REMOTELY); + } } /** @@ -1358,8 +1674,9 @@ void processAck(ServerTransaction serverTransaction, callParticipant.setSdpDescription( new String(ackRequest.getRawContent())); } - //change status - callParticipant.setState(CallParticipantState.CONNECTED); + // change status + if (!CallParticipantState.isOnHold(callParticipant.getState())) + callParticipant.setState(CallParticipantState.CONNECTED); } /** @@ -1470,16 +1787,16 @@ public synchronized void hangupCallParticipant(CallParticipant participant) CallParticipantSipImpl callParticipant = (CallParticipantSipImpl)participant; - Dialog dialog = callParticipant.getDialog(); - if (callParticipant.getState().equals(CallParticipantState.CONNECTED)) + CallParticipantState participantState = callParticipant.getState(); + if (participantState.equals(CallParticipantState.CONNECTED) + || CallParticipantState.isOnHold(participantState)) { sayBye(callParticipant); callParticipant.setState(CallParticipantState.DISCONNECTED); } - else if (callParticipant.getState() - .equals(CallParticipantState.CONNECTING) - || callParticipant.getState() - .equals(CallParticipantState.ALERTING_REMOTE_SIDE)) + else if (participantState.equals(CallParticipantState.CONNECTING) + || participantState + .equals(CallParticipantState.ALERTING_REMOTE_SIDE)) { if (callParticipant.getFirstTransaction() != null) { @@ -1489,18 +1806,17 @@ else if (callParticipant.getState() } callParticipant.setState(CallParticipantState.DISCONNECTED); } - else if (callParticipant.getState() - .equals(CallParticipantState.INCOMING_CALL)) + else if (participantState.equals(CallParticipantState.INCOMING_CALL)) { callParticipant.setState(CallParticipantState.DISCONNECTED); sayBusyHere(callParticipant); } //For FAILE and BUSY we only need to update CALL_STATUS - else if (callParticipant.getState().equals(CallParticipantState.BUSY)) + else if (participantState.equals(CallParticipantState.BUSY)) { callParticipant.setState(CallParticipantState.DISCONNECTED); } - else if (callParticipant.getState().equals(CallParticipantState.FAILED)) + else if (participantState.equals(CallParticipantState.FAILED)) { callParticipant.setState(CallParticipantState.DISCONNECTED); } @@ -1783,7 +2099,10 @@ public synchronized void answerCallParticipant(CallParticipant participant) , OperationFailedException.INTERNAL_ERROR); } - if(participant.getState().equals(CallParticipantState.CONNECTED)) + CallParticipantState participantState = participant.getState(); + + if (participantState.equals(CallParticipantState.CONNECTED) + || CallParticipantState.isOnHold(participantState)) { logger.info("Ignoring user request to answer a CallParticipant " + "that is already connected. CP:" + participant); diff --git a/src/net/java/sip/communicator/service/media/CallSession.java b/src/net/java/sip/communicator/service/media/CallSession.java index de7cac57b..b83bd889f 100644 --- a/src/net/java/sip/communicator/service/media/CallSession.java +++ b/src/net/java/sip/communicator/service/media/CallSession.java @@ -20,10 +20,11 @@ * single Call may only be associated one CallSession * instance. *- * A call session also allows signalling protocols to generate SDP offers and + * A call session also allows signaling protocols to generate SDP offers and * construct sdp answers. * * @author Emil Ivov + * @author Lubomir Marinov */ public interface CallSession { @@ -31,7 +32,7 @@ public interface CallSession * The method is meant for use by protocol service implementations when * willing to send an invitation to a remote callee. * - * @return a String containing an SDP offer descibing parameters of the + * @return a String containing an SDP offer describing parameters of the * Call associated with this session. * @throws MediaException code INTERNAL_ERROR if generating the offer fails * for some reason. @@ -56,6 +57,54 @@ public String createSdpOffer() public String createSdpOffer(InetAddress intendedDestination) throws MediaException; + /** + * The method is meant for use by protocol service implementations when + * willing to send an in-dialog invitation to a remote callee to put her + * on/off hold or to send an answer to an offer to be put on/off hold. + * + * @param participantSdpDescription the last SDP description of the remote + * callee + * @param on true if the SDP description should offer the remote + * callee to be put on hold or answer an offer from the remote + * callee to be put on hold; false to work in the + * context of a put-off-hold offer + * @return an SDP description String which offers the remote + * callee to be put her on/off hold or answers an offer from the + * remote callee to be put on/off hold + * @throws MediaException + */ + public String createSdpDescriptionForHold(String participantSdpDescription, + boolean on) throws MediaException; + + /** + * Determines whether a specific SDP description String offers + * this party to be put on hold. + * + * @param sdpOffer the SDP description String to be examined for + * an offer to this party to be put on hold + * @return true if the specified SDP description String + * offers this party to be put on hold; false, otherwise + * @throws MediaException + */ + public boolean isSdpOfferToHold(String sdpOffer) throws MediaException; + + /** + * Puts the media of this CallSession on/off hold depending on + * the origin of the request. + *
+ * For example, a remote request to have this party put off hold cannot + * override an earlier local request to put the remote party on hold. + *
+ * + * @param on true to request the media of this + * CallSession be put on hold; false, + * otherwise + * @param here true if the request comes from this side of the + * call; false if the remote party is the issuer of + * the request i.e. it's the result of a remote offer + */ + public void putOnHold(boolean on, boolean here); + /** * The method is meant for use by protocol service implementations when * willing to respond to an invitation received from a remote caller. Apart @@ -65,7 +114,7 @@ public String createSdpOffer(InetAddress intendedDestination) * @param sdpOffer the SDP offer that we'd like to create an answer for. * @param offerer the participant that has sent the offer. * - * @return a String containing an SDP answer descibing parameters of the + * @return a String containing an SDP answer describing parameters of the * Call associated with this session and matching those advertised * by the caller in their sdpOffer. * @@ -111,7 +160,7 @@ public void processSdpAnswer(CallParticipant responder, String sdpAnswer) public int getAudioPort(); /** - * Returns a URL pointing ta a location with call control information for + * Returns a URL pointing to a location with call control information for * this call or null if no such URL is available. * * @return a URL link to a location with call information or a call control diff --git a/src/net/java/sip/communicator/service/protocol/CallParticipantState.java b/src/net/java/sip/communicator/service/protocol/CallParticipantState.java index b63a34206..d749a7b99 100644 --- a/src/net/java/sip/communicator/service/protocol/CallParticipantState.java +++ b/src/net/java/sip/communicator/service/protocol/CallParticipantState.java @@ -27,12 +27,13 @@ *A FAILED state is prone to appear at any place in the above diagram and is * generally followed by a disconnected state. * - *
Information on call participant is shonw in the phone user interface until + *
Information on call participant is shown in the phone user interface until
* they enter the DISCONNECTED state. At that point call participant information
* is automatically removed from the user interface and the call is considered
* terminated.
*
* @author Emil Ivov
+ * @author Lubomir Marinov
*/
public class CallParticipantState
{
@@ -179,18 +180,67 @@ public class CallParticipantState
= new CallParticipantState(_FAILED);
/**
- * This constant value indicates a String representation of the ON_HOLD
- * call state.
- *
This constant has the String value "On Hold".
+ * The constant value being a String representation of the ON_HOLD_LOCALLY
+ * call participant state.
+ *
+ * This constant has the String value "Locally On Hold". + *
*/ - public static final String _ON_HOLD = "On Hold"; + public static final String _ON_HOLD_LOCALLY = "Locally On Hold"; /** - * This constant value indicates that the state of the call participant is - * is ON_HOLD - which means that an attempt to establish a call with that - * participant has failed for an unexpected reason. + * The constant value indicating that the state of a call participant is + * locally put on hold. + */ + public static final CallParticipantState ON_HOLD_LOCALLY + = new CallParticipantState(_ON_HOLD_LOCALLY); + + /** + * The constant value being a String representation of the ON_HOLD_MUTUALLY + * call participant state. + *+ * This constant has the String value "Mutually On Hold". + *
*/ - public static final CallParticipantState ON_HOLD - = new CallParticipantState(_ON_HOLD); + public static final String _ON_HOLD_MUTUALLY = "Mutually On Hold"; + /** + * The constant value indicating that the state of a call participant is + * mutually - locally and remotely - put on hold. + */ + public static final CallParticipantState ON_HOLD_MUTUALLY + = new CallParticipantState(_ON_HOLD_MUTUALLY); + + /** + * The constant value being a String representation of the ON_HOLD_REMOTELY + * call participant state. + *+ * This constant has the String value "Remotely On Hold". + *
+ */ + public static final String _ON_HOLD_REMOTELY = "Remotely On Hold"; + /** + * The constant value indicating that the state of a call participant is + * remotely put on hold. + */ + public static final CallParticipantState ON_HOLD_REMOTELY + = new CallParticipantState(_ON_HOLD_REMOTELY); + + /** + * Determines whether a specific CallParticipantState value + * signal a call hold regardless of the issuer (which may be local and/or + * remote). + * + * @param state + * the CallParticipantState value to be checked + * whether it signals a call hold + * @return true if the specified state signals a call + * hold; false, otherwise + */ + public static final boolean isOnHold(CallParticipantState state) + { + return CallParticipantState.ON_HOLD_LOCALLY.equals(state) + || CallParticipantState.ON_HOLD_MUTUALLY.equals(state) + || CallParticipantState.ON_HOLD_REMOTELY.equals(state); + } /** * A string representationf this Participant Call State. Could be @@ -221,10 +271,10 @@ public String getStateString() } /** - * Returns a string represenation of this call state. Strings returned + * Returns a string representation of this call state. Strings returned * by this method have the following format: * CallParticipantState:+ * Extend this class to create a CallParticipantChangeEvent listener + * and override the methods for the events of interest. (If you implement the + * CallParticipantListener interface, you have to define all of the + * methods in it. This abstract class defines null methods for them all, so you + * only have to define methods for events you care about.) + *
+ * + * @see CallParticipantChangeEvent + * @see CallParticipantListener + * + * @author Lubomir Marinov + */ +public abstract class CallParticipantAdapter + implements CallParticipantListener +{ + + /** + * Indicates that a change has occurred in the address of the source + * CallParticipant. + * + * @param evt The CallParticipantChangeEvent instance containing + * the source event as well as its previous and its new address. + */ + public void participantAddressChanged(CallParticipantChangeEvent evt) + { + } + + /** + * Indicates that a change has occurred in the display name of the source + * CallParticipant. + * + * @param evt The CallParticipantChangeEvent instance containing + * the source event as well as its previous and its new display + * names. + */ + public void participantDisplayNameChanged(CallParticipantChangeEvent evt) + { + } + + /** + * Indicates that a change has occurred in the image of the source + * CallParticipant. + * + * @param evt The CallParticipantChangeEvent instance containing + * the source event as well as its previous and its new image. + */ + public void participantImageChanged(CallParticipantChangeEvent evt) + { + } + + /** + * Indicates that a change has occurred in the status of the source + * CallParticipant. + * + * @param evt The CallParticipantChangeEvent instance containing + * the source event as well as its previous and its new status. + */ + public void participantStateChanged(CallParticipantChangeEvent evt) + { + } + + /** + * Indicates that a change has occurred in the transport address that we use + * to communicate with the participant. + * + * @param evt The CallParticipantChangeEvent instance containing + * the source event as well as its previous and its new transport + * address. + */ + public void participantTransportAddressChanged( + CallParticipantChangeEvent evt) + { + } +} diff --git a/test/net/java/sip/communicator/slick/protocol/jabber/TestOperationSetBasicTelephonyJabberImpl.java b/test/net/java/sip/communicator/slick/protocol/jabber/TestOperationSetBasicTelephonyJabberImpl.java index 3bebd49b7..6e1c6e4eb 100644 --- a/test/net/java/sip/communicator/slick/protocol/jabber/TestOperationSetBasicTelephonyJabberImpl.java +++ b/test/net/java/sip/communicator/slick/protocol/jabber/TestOperationSetBasicTelephonyJabberImpl.java @@ -858,7 +858,7 @@ public void callEnded(CallEvent event) * status changes. */ public class CallParticipantStateEventCollector - implements CallParticipantListener + extends CallParticipantAdapter { public ArrayList collectedEvents = new ArrayList(); private CallParticipant listenedCallParticipant = null; @@ -902,37 +902,6 @@ public void participantStateChanged(CallParticipantChangeEvent event) } } - /** - * Unused by this collector. - * @param event ignored. - */ - public void participantImageChanged(CallParticipantChangeEvent event) - {} - - /** - * Unused by this collector - * @param event ignored. - */ - public void participantAddressChanged(CallParticipantChangeEvent event) - {} - - /** - * Unused by this collector - * @param event ignored. - */ - public void participantTransportAddressChanged( - CallParticipantChangeEvent event) - {} - - - /** - * Unused by this collector - * @param event ignored. - */ - public void participantDisplayNameChanged( - CallParticipantChangeEvent event) - {} - /** * Blocks until an event notifying us of the awaited state change is * received or until waitFor miliseconds pass (whichever happens first). diff --git a/test/net/java/sip/communicator/slick/protocol/sip/TestOperationSetBasicTelephonySipImpl.java b/test/net/java/sip/communicator/slick/protocol/sip/TestOperationSetBasicTelephonySipImpl.java index 2b6c6751d..21d3508e6 100644 --- a/test/net/java/sip/communicator/slick/protocol/sip/TestOperationSetBasicTelephonySipImpl.java +++ b/test/net/java/sip/communicator/slick/protocol/sip/TestOperationSetBasicTelephonySipImpl.java @@ -857,7 +857,7 @@ public void callEnded(CallEvent event) * status changes. */ public class CallParticipantStateEventCollector - implements CallParticipantListener + extends CallParticipantAdapter { public ArrayList collectedEvents = new ArrayList(); private CallParticipant listenedCallParticipant = null; @@ -901,37 +901,6 @@ public void participantStateChanged(CallParticipantChangeEvent event) } } - /** - * Unused by this collector. - * @param event ignored. - */ - public void participantImageChanged(CallParticipantChangeEvent event) - {} - - /** - * Unused by this collector - * @param event ignored. - */ - public void participantAddressChanged(CallParticipantChangeEvent event) - {} - - /** - * Unused by this collector - * @param event ignored. - */ - public void participantTransportAddressChanged( - CallParticipantChangeEvent event) - {} - - - /** - * Unused by this collector - * @param event ignored. - */ - public void participantDisplayNameChanged( - CallParticipantChangeEvent event) - {} - /** * Blocks until an event notifying us of the awaited state change is * received or until waitFor miliseconds pass (whichever happens first).