diff options
Diffstat (limited to 'java/com/android/dialer/enrichedcall/EnrichedCallManager.java')
-rw-r--r-- | java/com/android/dialer/enrichedcall/EnrichedCallManager.java | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/java/com/android/dialer/enrichedcall/EnrichedCallManager.java b/java/com/android/dialer/enrichedcall/EnrichedCallManager.java new file mode 100644 index 000000000..0d3ed9e43 --- /dev/null +++ b/java/com/android/dialer/enrichedcall/EnrichedCallManager.java @@ -0,0 +1,324 @@ +/* + * Copyright (C) 2016 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ + +package com.android.dialer.enrichedcall; + +import android.support.annotation.IntDef; +import android.support.annotation.MainThread; +import android.support.annotation.NonNull; +import android.support.annotation.Nullable; +import com.android.dialer.calldetails.CallDetailsEntries; +import com.android.dialer.calldetails.CallDetailsEntries.CallDetailsEntry; +import com.android.dialer.enrichedcall.historyquery.proto.HistoryResult; +import com.android.dialer.enrichedcall.videoshare.VideoShareListener; +import com.android.dialer.multimedia.MultimediaData; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.util.List; +import java.util.Map; + +/** Performs all enriched calling logic. */ +public interface EnrichedCallManager { + + int POST_CALL_NOTE_MAX_CHAR = 60; + + /** Receives updates when enriched call capabilities are ready. */ + interface CapabilitiesListener { + + /** Callback fired when the capabilities are updated. */ + @MainThread + void onCapabilitiesUpdated(); + } + + /** + * Registers the given {@link CapabilitiesListener}. + * + * <p>As a result of this method, the listener will receive a call to {@link + * CapabilitiesListener#onCapabilitiesUpdated()} after a call to {@link + * #requestCapabilities(String)}. + */ + @MainThread + void registerCapabilitiesListener(@NonNull CapabilitiesListener listener); + + /** + * Starts an asynchronous process to get enriched call capabilities of the given number. + * + * <p>Registered listeners will receive a call to {@link + * CapabilitiesListener#onCapabilitiesUpdated()} on completion. + * + * @param number the remote number in any format + */ + @MainThread + void requestCapabilities(@NonNull String number); + + /** + * Unregisters the given {@link CapabilitiesListener}. + * + * <p>As a result of this method, the listener will not receive capabilities of the given number. + */ + @MainThread + void unregisterCapabilitiesListener(@NonNull CapabilitiesListener listener); + + /** Gets the cached capabilities for the given number, else null */ + @MainThread + @Nullable + EnrichedCallCapabilities getCapabilities(@NonNull String number); + + /** Clears any cached data, such as capabilities. */ + @MainThread + void clearCachedData(); + + /** Possible states for call composer sessions. */ + @Retention(RetentionPolicy.SOURCE) + @IntDef({ + STATE_NONE, + STATE_STARTING, + STATE_STARTED, + STATE_START_FAILED, + STATE_MESSAGE_SENT, + STATE_MESSAGE_FAILED, + STATE_CLOSED, + }) + @interface State {} + + int STATE_NONE = 0; + int STATE_STARTING = STATE_NONE + 1; + int STATE_STARTED = STATE_STARTING + 1; + int STATE_START_FAILED = STATE_STARTED + 1; + int STATE_MESSAGE_SENT = STATE_START_FAILED + 1; + int STATE_MESSAGE_FAILED = STATE_MESSAGE_SENT + 1; + int STATE_CLOSED = STATE_MESSAGE_FAILED + 1; + + /** + * Starts a call composer session with the given remote number. + * + * @param number the remote number in any format + * @return the id for the started session, or {@link Session#NO_SESSION_ID} if the session fails + */ + @MainThread + long startCallComposerSession(@NonNull String number); + + /** + * Sends the given information through an open enriched call session. As per the enriched calling + * spec, up to two messages are sent: the first is an enriched call data message that optionally + * includes the subject and the second is the optional image data message. + * + * @param sessionId the id for the session. See {@link #startCallComposerSession(String)} + * @param data the {@link MultimediaData} + * @throws IllegalArgumentException if there's no open session with the given number + * @throws IllegalStateException if the session isn't in the {@link #STATE_STARTED} state + */ + @MainThread + void sendCallComposerData(long sessionId, @NonNull MultimediaData data); + + /** + * Ends the given call composer session. Ending a session means that the call composer session + * will be closed. + * + * @param sessionId the id of the session to end + */ + @MainThread + void endCallComposerSession(long sessionId); + + /** + * Sends a post call note to the given number. + * + * @throws IllegalArgumentException if message is longer than {@link #POST_CALL_NOTE_MAX_CHAR} + * characters + */ + @MainThread + void sendPostCallNote(@NonNull String number, @NonNull String message); + + /** + * Called once the capabilities are available for a corresponding call to {@link + * #requestCapabilities(String)}. + * + * @param number the remote number in any format + * @param capabilities the supported capabilities + */ + @MainThread + void onCapabilitiesReceived( + @NonNull String number, @NonNull EnrichedCallCapabilities capabilities); + + /** Receives updates when the state of an enriched call changes. */ + interface StateChangedListener { + + /** + * Callback fired when state changes. Listeners should call {@link #getSession(long)} or {@link + * #getSession(String, String, Filter)} to retrieve the new state. + */ + void onEnrichedCallStateChanged(); + } + + /** + * Registers the given {@link StateChangedListener}. + * + * <p>As a result of this method, the listener will receive updates when the state of any enriched + * call changes. + */ + @MainThread + void registerStateChangedListener(@NonNull StateChangedListener listener); + + /** + * Returns the {@link Session} for the given unique call id, falling back to the number. If a + * filter is provided, it will be applied to both the uniqueCalId and number lookups. + */ + @MainThread + @Nullable + Session getSession(@NonNull String uniqueCallId, @NonNull String number, @Nullable Filter filter); + + /** Returns the {@link Session} for the given sessionId, or {@code null} if no session exists. */ + @MainThread + @Nullable + Session getSession(long sessionId); + + @NonNull + Filter createIncomingCallComposerFilter(); + + @NonNull + Filter createOutgoingCallComposerFilter(); + + /** + * Starts an asynchronous process to get all historical data for the given number and set of + * {@link CallDetailsEntries}. + */ + @MainThread + void requestAllHistoricalData(@NonNull String number, @NonNull CallDetailsEntries entries); + + /** + * Returns a mapping of enriched call data for all of the given {@link CallDetailsEntries}, which + * should not be modified. A {@code null} return indicates that clients should call {@link + * #requestAllHistoricalData(String, CallDetailsEntries)}. + * + * <p>The mapping is created by finding the HistoryResults whose timestamps occurred during or + * close after a CallDetailsEntry. A CallDetailsEntry can have multiple HistoryResults in the + * event that both a CallComposer message and PostCall message were sent for the same call. + */ + @Nullable + @MainThread + Map<CallDetailsEntry, List<HistoryResult>> getAllHistoricalData( + @NonNull String number, @NonNull CallDetailsEntries entries); + + /** + * Unregisters the given {@link StateChangedListener}. + * + * <p>As a result of this method, the listener will not receive updates when the state of enriched + * calls changes. + */ + @MainThread + void unregisterStateChangedListener(@NonNull StateChangedListener listener); + + /** + * Called when the status of an enriched call session changes. + * + * + * @throws IllegalArgumentException if the state is invalid + */ + @MainThread + void onSessionStatusUpdate(long sessionId, @NonNull String number, int state); + + /** + * Called when the status of an enriched call message updates. + * + * + * @throws IllegalArgumentException if the state is invalid + * @throws IllegalStateException if there's no session for the given id + */ + @MainThread + void onMessageUpdate(long sessionId, @NonNull String messageId, int state); + + /** + * Called when call composer data arrives for the given session. + * + * @throws IllegalStateException if there's no session for the given id + */ + @MainThread + void onIncomingCallComposerData(long sessionId, @NonNull MultimediaData multimediaData); + + /** + * Called when post call data arrives for the given session. + * + * @throws IllegalStateException if there's no session for the given id + */ + @MainThread + void onIncomingPostCallData(long sessionId, @NonNull MultimediaData multimediaData); + + /** + * Registers the given {@link VideoShareListener}. + * + * <p>As a result of this method, the listener will receive updates when any video share state + * changes. + */ + @MainThread + void registerVideoShareListener(@NonNull VideoShareListener listener); + + /** + * Unregisters the given {@link VideoShareListener}. + * + * <p>As a result of this method, the listener will not receive updates when any video share state + * changes. + */ + @MainThread + void unregisterVideoShareListener(@NonNull VideoShareListener listener); + + /** + * Called when an incoming video share invite is received. + * + * @return whether or not the invite was accepted by the manager (rejected when disabled) + */ + @MainThread + boolean onIncomingVideoShareInvite(long sessionId, @NonNull String number); + + /** + * Starts a video share session with the given remote number. + * + * @param number the remote number in any format + * @return the id for the started session, or {@link Session#NO_SESSION_ID} if the session fails + */ + @MainThread + long startVideoShareSession(@NonNull String number); + + /** + * Accepts a video share session invite. + * + * @param sessionId the session to accept + * @return whether or not accepting the session succeeded + */ + @MainThread + boolean acceptVideoShareSession(long sessionId); + + /** + * Retrieve the session id for an incoming video share invite. + * + * @param number the remote number in any format + * @return the id for the session invite, or {@link Session#NO_SESSION_ID} if there is no invite + */ + @MainThread + long getVideoShareInviteSessionId(@NonNull String number); + + /** + * Ends the given video share session. + * + * @param sessionId the id of the session to end + */ + @MainThread + void endVideoShareSession(long sessionId); + + /** Interface for filtering sessions (compatible with Predicate from Java 8) */ + interface Filter { + boolean test(Session session); + } +} |