001/*
002 * Copyright (c) 2011-2017 Nexmo Inc
003 *
004 * Permission is hereby granted, free of charge, to any person obtaining a copy
005 * of this software and associated documentation files (the "Software"), to deal
006 * in the Software without restriction, including without limitation the rights
007 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
008 * copies of the Software, and to permit persons to whom the Software is
009 * furnished to do so, subject to the following conditions:
010 *
011 * The above copyright notice and this permission notice shall be included in
012 * all copies or substantial portions of the Software.
013 *
014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
015 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
016 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
017 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
018 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
019 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
020 * THE SOFTWARE.
021 */
022package com.nexmo.client.voice.endpoints;
023
024import com.nexmo.client.HttpWrapper;
025import com.nexmo.client.NexmoClientException;
026import com.nexmo.client.voice.*;
027
028import java.io.IOException;
029
030/**
031 * Allows actions to be taken on <tt>/calls/*</tt> endpoints.
032 * <p>
033 * <b>Note:</b> This is an internal object. All functionality is provided publicly by the {@link VoiceClient} class.
034 */
035public class CallsEndpoint {
036    private final CreateCallMethod createCall;
037    private final ReadCallMethod readCall;
038    private final ListCallsMethod listCalls;
039    private final ModifyCallMethod modifyCall;
040
041    /**
042     * Constructor.
043     *
044     * @param httpWrapper (required) shared HTTP wrapper object used for making REST calls.
045     */
046    public CallsEndpoint(HttpWrapper httpWrapper) {
047        this.createCall = new CreateCallMethod(httpWrapper);
048        this.readCall = new ReadCallMethod(httpWrapper);
049        this.listCalls = new ListCallsMethod(httpWrapper);
050        this.modifyCall = new ModifyCallMethod(httpWrapper);
051    }
052
053    /**
054     * Start a call configured by the provided {@link Call} object.
055     * <p>
056     * Requires a {@link com.nexmo.client.auth.JWTAuthMethod} to be provided to the NexmoClient which constructs
057     *
058     * @param callRequest A Call object configuring the call to be created
059     * @return A CallEvent describing the call that was initiated.
060     * @throws IOException          if an error occurs communicating with the Nexmo API
061     * @throws NexmoClientException if an error occurs constructing the Nexmo API request or response
062     */
063    public CallEvent post(Call callRequest) throws IOException, NexmoClientException {
064        return this.createCall.execute(callRequest);
065    }
066
067    /**
068     * List previous and ongoing calls which match the provided <tt>filter</tt>.
069     *
070     * @param filter A CallsFilter describing the calls to be searched, or {@code null} for all calls.
071     * @return A CallInfoPage containing a single page of {@link CallInfo} results
072     * @throws IOException          if an error occurs communicating with the Nexmo API
073     * @throws NexmoClientException if an error occurs constructing the Nexmo API request or response
074     */
075    public CallInfoPage get(CallsFilter filter) throws IOException, NexmoClientException {
076        return this.listCalls.execute(filter);
077    }
078
079    /**
080     * Get details of a single call, identified by <tt>uuid</tt>.
081     *
082     * @param uuid The uuid of the CallInfo object to be retrieved
083     * @return A CallInfo object describing the state of the call that was made or is in progress
084     * @throws IOException          if an error occurs communicating with the Nexmo API
085     * @throws NexmoClientException if an error occurs constructing the Nexmo API request or response
086     */
087    public CallInfo get(String uuid) throws IOException, NexmoClientException {
088        return this.readCall.execute(uuid);
089    }
090
091
092    /**
093     * Modify an ongoing call.
094     * <p>
095     * Currently this method only supports the "hangup" action.
096     *
097     * @param uuid   The uuid of the CallInfo object to be modified
098     * @param action The word "hangup"
099     * @return A ModifyCallResponse object describing the state of the call that was modified
100     * @throws IOException          if an error occurs communicating with the Nexmo API
101     * @throws NexmoClientException if an error occurs constructing the Nexmo API request or response
102     */
103    public ModifyCallResponse put(String uuid, String action) throws IOException, NexmoClientException {
104        return this.modifyCall.execute(new CallModifier(uuid, action));
105    }
106}