/*
* 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 android.media.tv;
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.annotation.SystemApi;
import android.content.Context;
import android.media.tv.TvInputManager;
import android.net.Uri;
import android.os.Bundle;
import android.os.Handler;
import android.os.Looper;
import android.text.TextUtils;
import android.util.Log;
import android.util.Pair;
import java.util.ArrayDeque;
import java.util.Queue;
/**
* The public interface object used to interact with a specific TV input service for TV program
* recording.
*/
public class TvRecordingClient {
private static final String TAG = "TvRecordingClient";
private static final boolean DEBUG = false;
private final RecordingCallback mCallback;
private final Handler mHandler;
private final TvInputManager mTvInputManager;
private TvInputManager.Session mSession;
private MySessionCallback mSessionCallback;
private boolean mIsRecordingStarted;
private boolean mIsTuned;
private final Queue<Pair<String, Bundle>> mPendingAppPrivateCommands = new ArrayDeque<>();
/**
* Creates a new TvRecordingClient object.
*
* @param context The application context to create a TvRecordingClient with.
* @param tag A short name for debugging purposes.
* @param callback The callback to receive recording status changes.
* @param handler The handler to invoke the callback on.
*/
public TvRecordingClient(Context context, String tag, @NonNull RecordingCallback callback,
Handler handler) {
mCallback = callback;
mHandler = handler == null ? new Handler(Looper.getMainLooper()) : handler;
mTvInputManager = (TvInputManager) context.getSystemService(Context.TV_INPUT_SERVICE);
}
/**
* Tunes to a given channel for TV program recording. The first tune request will create a new
* recording session for the corresponding TV input and establish a connection between the
* application and the session. If recording has already started in the current recording
* session, this method throws an exception.
*
* <p>The application may call this method before starting or after stopping recording, but not
* during recording.
*
* <p>The recording session will respond by calling
* {@link RecordingCallback#onTuned(Uri)} if the tune request was fulfilled, or
* {@link RecordingCallback#onError(int)} otherwise.
*
* @param inputId The ID of the TV input for the given channel.
* @param channelUri The URI of a channel.
* @throws IllegalStateException If recording is already started.
*/
public void tune(String inputId, Uri channelUri) {
tune(inputId, channelUri, null);
}
/**
* Tunes to a given channel for TV program recording. The first tune request will create a new
* recording session for the corresponding TV input and establish a connection between the
* application and the session. If recording has already started in the current recording
* session, this method throws an exception. This can be used to provide domain-specific
* features that are only known between certain client and their TV inputs.
*
* <p>The application may call this method before starting or after stopping recording, but not
* during recording.
*
* <p>The recording session will respond by calling
* {@link RecordingCallback#onTuned(Uri)} if the tune request was fulfilled, or
* {@link RecordingCallback#onError(int)} otherwise.
*
* @param inputId The ID of the TV input for the given channel.
* @param channelUri The URI of a channel.
* @param params Domain-specific data for this tune request. Keys <em>must</em> be a scoped
* name, i.e. prefixed with a package name you own, so that different developers will
* not create conflicting keys.
* @throws IllegalStateException If recording is already started.
*/
public void tune(String inputId, Uri channelUri, Bundle params) {
if (DEBUG) Log.d(TAG, "tune(" + channelUri + ")");
if (TextUtils.isEmpty(inputId)) {
throw new IllegalArgumentException("inputId cannot be null or an empty string");
}
if (mIsRecordingStarted) {
throw new IllegalStateException("tune failed - recording already started");
}
if (mSessionCallback != null && TextUtils.equals(mSessionCallback.mInputId, inputId)) {
if (mSession != null) {
mSession.tune(channelUri, params);
} else {
mSessionCallback.mChannelUri = channelUri;
mSessionCallback.mConnectionParams = params;
}
} else {
resetInternal();
mSessionCallback = new MySessionCallback(inputId, channelUri, params);
if (mTvInputManager != null) {
mTvInputManager.createRecordingSession(inputId, mSessionCallback, mHandler);
}
}
}
/**
* Releases the resources in the current recording session immediately. This may be called at
* any time, however if the session is already released, it does nothing.
*/
public void release() {
if (DEBUG) Log.d(TAG, "release()");
resetInternal();
}
private void resetInternal() {
mSessionCallback = null;
mPendingAppPrivateCommands.clear();
if (mSession != null) {
mSession.release();
mSession = null;
}
}
/**
* Starts TV program recording in the current recording session. Recording is expected to start
* immediately when this method is called. If the current recording session has not yet tuned to
* any channel, this method throws an exception.
*
* <p>The application may supply the URI for a TV program for filling in program specific data
* fields in the {@link android.media.tv.TvContract.RecordedPrograms} table.
* A non-null {@code programUri} implies the started recording should be of that specific
* program, whereas null {@code programUri} does not impose such a requirement and the
* recording can span across multiple TV programs. In either case, the application must call
* {@link TvRecordingClient#stopRecording()} to stop the recording.
*
* <p>The recording session will respond by calling {@link RecordingCallback#onError(int)} if
* the start request cannot be fulfilled.
*
* @param programUri The URI for the TV program to record, built by
* {@link TvContract#buildProgramUri(long)}. Can be {@code null}.
* @throws IllegalStateException If {@link #tune} request hasn't been handled yet.
*/
public void startRecording(@Nullable Uri programUri) {
if (!mIsTuned) {
throw new IllegalStateException("startRecording failed - not yet tuned");
}
if (mSession != null) {
mSession.startRecording(programUri);
mIsRecordingStarted = true;
}
}
/**
* Stops TV program recording in the current recording session. Recording is expected to stop
* immediately when this method is called. If recording has not yet started in the current
* recording session, this method does nothing.
*
* <p>The recording session is expected to create a new data entry in the
* {@link android.media.tv.TvContract.RecordedPrograms} table that describes the newly
* recorded program and pass the URI to that entry through to
* {@link RecordingCallback#onRecordingStopped(Uri)}.
* If the stop request cannot be fulfilled, the recording session will respond by calling
* {@link RecordingCallback#onError(int)}.
*/
public void stopRecording() {
if (!mIsRecordingStarted) {
Log.w(TAG, "stopRecording failed - recording not yet started");
}
if (mSession != null) {
mSession.stopRecording();
}
}
/**
* Sends a private command to the underlying TV input. This can be used to provide
* domain-specific features that are only known between certain clients and their TV inputs.
*
* @param action The name of the private command to send. This <em>must</em> be a scoped name,
* i.e. prefixed with a package name you own, so that different developers will not
* create conflicting commands.
* @param data An optional bundle to send with the command.
*/
public void sendAppPrivateCommand(@NonNull String action, Bundle data) {
if (TextUtils.isEmpty(action)) {
throw new IllegalArgumentException("action cannot be null or an empty string");
}
if (mSession != null) {
mSession.sendAppPrivateCommand(action, data);
} else {
Log.w(TAG, "sendAppPrivateCommand - session not yet created (action \"" + action
+ "\" pending)");
mPendingAppPrivateCommands.add(Pair.create(action, data));
}
}
/**
* Callback used to receive various status updates on the
* {@link android.media.tv.TvInputService.RecordingSession}
*/
public abstract static class RecordingCallback {
/**
* This is called when an error occurred while establishing a connection to the recording
* session for the corresponding TV input.
*
* @param inputId The ID of the TV input bound to the current TvRecordingClient.
*/
public void onConnectionFailed(String inputId) {
}
/**
* This is called when the connection to the current recording session is lost.
*
* @param inputId The ID of the TV input bound to the current TvRecordingClient.
*/
public void onDisconnected(String inputId) {
}
/**
* This is called when the recording session has been tuned to the given channel and is
* ready to start recording.
*
* @param channelUri The URI of a channel.
*/
public void onTuned(Uri channelUri) {
}
/**
* This is called when the current recording session has stopped recording and created a
* new data entry in the {@link TvContract.RecordedPrograms} table that describes the newly
* recorded program.
*
* @param recordedProgramUri The URI for the newly recorded program.
*/
public void onRecordingStopped(Uri recordedProgramUri) {
}
/**
* This is called when an issue has occurred. It may be called at any time after the current
* recording session is created until it is released.
*
* @param error The error code. Should be one of the followings.
* <ul>
* <li>{@link TvInputManager#RECORDING_ERROR_UNKNOWN}
* <li>{@link TvInputManager#RECORDING_ERROR_INSUFFICIENT_SPACE}
* <li>{@link TvInputManager#RECORDING_ERROR_RESOURCE_BUSY}
* </ul>
*/
public void onError(@TvInputManager.RecordingError int error) {
}
/**
* This is invoked when a custom event from the bound TV input is sent to this client.
*
* @param inputId The ID of the TV input bound to this client.
* @param eventType The type of the event.
* @param eventArgs Optional arguments of the event.
* @hide
*/
@SystemApi
public void onEvent(String inputId, String eventType, Bundle eventArgs) {
}
}
private class MySessionCallback extends TvInputManager.SessionCallback {
final String mInputId;
Uri mChannelUri;
Bundle mConnectionParams;
MySessionCallback(String inputId, Uri channelUri, Bundle connectionParams) {
mInputId = inputId;
mChannelUri = channelUri;
mConnectionParams = connectionParams;
}
@Override
public void onSessionCreated(TvInputManager.Session session) {
if (DEBUG) {
Log.d(TAG, "onSessionCreated()");
}
if (this != mSessionCallback) {
Log.w(TAG, "onSessionCreated - session already created");
// This callback is obsolete.
if (session != null) {
session.release();
}
return;
}
mSession = session;
if (session != null) {
// Sends the pending app private commands.
for (Pair<String, Bundle> command : mPendingAppPrivateCommands) {
mSession.sendAppPrivateCommand(command.first, command.second);
}
mPendingAppPrivateCommands.clear();
mSession.tune(mChannelUri, mConnectionParams);
} else {
mSessionCallback = null;
if (mCallback != null) {
mCallback.onConnectionFailed(mInputId);
}
}
}
@Override
void onTuned(TvInputManager.Session session, Uri channelUri) {
if (DEBUG) {
Log.d(TAG, "onTuned()");
}
if (this != mSessionCallback) {
Log.w(TAG, "onTuned - session not created");
return;
}
mIsTuned = true;
mCallback.onTuned(channelUri);
}
@Override
public void onSessionReleased(TvInputManager.Session session) {
if (DEBUG) {
Log.d(TAG, "onSessionReleased()");
}
if (this != mSessionCallback) {
Log.w(TAG, "onSessionReleased - session not created");
return;
}
mIsTuned = false;
mIsRecordingStarted = false;
mSessionCallback = null;
mSession = null;
if (mCallback != null) {
mCallback.onDisconnected(mInputId);
}
}
@Override
public void onRecordingStopped(TvInputManager.Session session, Uri recordedProgramUri) {
if (DEBUG) {
Log.d(TAG, "onRecordingStopped(recordedProgramUri= " + recordedProgramUri + ")");
}
if (this != mSessionCallback) {
Log.w(TAG, "onRecordingStopped - session not created");
return;
}
mIsRecordingStarted = false;
mCallback.onRecordingStopped(recordedProgramUri);
}
@Override
public void onError(TvInputManager.Session session, int error) {
if (DEBUG) {
Log.d(TAG, "onError(error=" + error + ")");
}
if (this != mSessionCallback) {
Log.w(TAG, "onError - session not created");
return;
}
mCallback.onError(error);
}
@Override
public void onSessionEvent(TvInputManager.Session session, String eventType,
Bundle eventArgs) {
if (DEBUG) {
Log.d(TAG, "onSessionEvent(eventType=" + eventType + ", eventArgs=" + eventArgs
+ ")");
}
if (this != mSessionCallback) {
Log.w(TAG, "onSessionEvent - session not created");
return;
}
if (mCallback != null) {
mCallback.onEvent(mInputId, eventType, eventArgs);
}
}
}
}