Java tutorial
/* * 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); } } } }