Add Java interfaces to the common_time services. (08d7aeb0) · Commits · e / os / android_frameworks_base

core/java/android/os/CommonClock.java

0 → 100644

+682 −0

File added.

Preview size limit exceeded, changes collapsed.

core/java/android/os/CommonTimeConfig.java

0 → 100644

+447 −0

Original line number	Diff line number	Diff line
		/*
		* Copyright (C) 2012 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.os;

		import java.net.InetAddress;
		import java.net.InetSocketAddress;
		import java.util.NoSuchElementException;

		import android.os.IBinder;
		import android.os.RemoteException;
		import android.os.ServiceManager;

		/**
		* Used for configuring and controlling the status of the android common time service.
		* @hide
		*/
		public class CommonTimeConfig {
		/**
		* Successful operation.
		*/
		public static final int SUCCESS = 0;
		/**
		* Unspecified error.
		*/
		public static final int ERROR = -1;
		/**
		* Operation failed due to bad parameter value.
		*/
		public static final int ERROR_BAD_VALUE = -4;
		/**
		* Operation failed due to dead remote object.
		*/
		public static final int ERROR_DEAD_OBJECT = -7;

		/**
		* Sentinel value returned by {@link #getMasterElectionGroupId()} when an error occurs trying to
		* fetch the master election group.
		*/
		public static final long INVALID_GROUP_ID = -1;

		/**
		* Name of the underlying native binder service
		*/
		public static final String SERVICE_NAME = "common_time.config";

		/**
		* Class constructor.
		* @throws android.os.RemoteException
		*/
		public CommonTimeConfig()
		throws RemoteException {
		mRemote = ServiceManager.getService(SERVICE_NAME);
		if (null == mRemote)
		throw new RemoteException();

		mInterfaceDesc = mRemote.getInterfaceDescriptor();
		mUtils = new CommonTimeUtils(mRemote, mInterfaceDesc);
		mRemote.linkToDeath(mDeathHandler, 0);
		}

		/**
		* Handy class factory method.
		*/
		static public CommonTimeConfig create() {
		CommonTimeConfig retVal;

		try {
		retVal = new CommonTimeConfig();
		}
		catch (RemoteException e) {
		retVal = null;
		}

		return retVal;
		}

		/**
		* Release all native resources held by this {@link android.os.CommonTimeConfig} instance. Once
		* resources have been released, the {@link android.os.CommonTimeConfig} instance is
		* disconnected from the native service and will throw a {@link android.os.RemoteException} if
		* any of its methods are called. Clients should always call release on their client instances
		* before releasing their last Java reference to the instance. Failure to do this will cause
		* non-deterministic native resource reclamation and may cause the common time service to remain
		* active on the network for longer than it should.
		*/
		public void release() {
		if (null != mRemote) {
		try {
		mRemote.unlinkToDeath(mDeathHandler, 0);
		}
		catch (NoSuchElementException e) { }
		mRemote = null;
		}
		mUtils = null;
		}

		/**
		* Gets the current priority of the common time service used in the master election protocol.
		*
		* @return an 8 bit value indicating the priority of this common time service relative to other
		* common time services operating in the same domain.
		* @throws android.os.RemoteException
		*/
		public byte getMasterElectionPriority()
		throws RemoteException {
		throwOnDeadServer();
		return (byte)mUtils.transactGetInt(METHOD_GET_MASTER_ELECTION_PRIORITY, -1);
		}

		/**
		* Sets the current priority of the common time service used in the master election protocol.
		*
		* @param priority priority of the common time service used in the master election protocol.
		* Lower numbers are lower priority.
		* @return {@link #SUCCESS} in case of success,
		* {@link #ERROR} or {@link #ERROR_DEAD_OBJECT} in case of failure.
		*/
		public int setMasterElectionPriority(byte priority) {
		if (checkDeadServer())
		return ERROR_DEAD_OBJECT;
		return mUtils.transactSetInt(METHOD_SET_MASTER_ELECTION_PRIORITY, priority);
		}

		/**
		* Gets the IP endpoint used by the time service to participate in the master election protocol.
		*
		* @return an InetSocketAddress containing the IP address and UDP port being used by the
		* system's common time service to participate in the master election protocol.
		* @throws android.os.RemoteException
		*/
		public InetSocketAddress getMasterElectionEndpoint()
		throws RemoteException {
		throwOnDeadServer();
		return mUtils.transactGetSockaddr(METHOD_GET_MASTER_ELECTION_ENDPOINT);
		}

		/**
		* Sets the IP endpoint used by the common time service to participate in the master election
		* protocol.
		*
		* @param ep The IP address and UDP port to be used by the common time service to participate in
		* the master election protocol. The supplied IP address must be either the broadcast or
		* multicast address, unicast addresses are considered to be illegal values.
		* @return {@link #SUCCESS} in case of success,
		* {@link #ERROR}, {@link #ERROR_BAD_VALUE} or {@link #ERROR_DEAD_OBJECT} in case of failure.
		*/
		public int setMasterElectionEndpoint(InetSocketAddress ep) {
		if (checkDeadServer())
		return ERROR_DEAD_OBJECT;
		return mUtils.transactSetSockaddr(METHOD_SET_MASTER_ELECTION_ENDPOINT, ep);
		}

		/**
		* Gets the current group ID used by the common time service in the master election protocol.
		*
		* @return The 64-bit group ID of the common time service.
		* @throws android.os.RemoteException
		*/
		public long getMasterElectionGroupId()
		throws RemoteException {
		throwOnDeadServer();
		return mUtils.transactGetLong(METHOD_GET_MASTER_ELECTION_GROUP_ID, INVALID_GROUP_ID);
		}

		/**
		* Sets the current group ID used by the common time service in the master election protocol.
		*
		* @param id The 64-bit group ID of the common time service.
		* @return {@link #SUCCESS} in case of success,
		* {@link #ERROR}, {@link #ERROR_BAD_VALUE} or {@link #ERROR_DEAD_OBJECT} in case of failure.
		*/
		public int setMasterElectionGroupId(long id) {
		if (checkDeadServer())
		return ERROR_DEAD_OBJECT;
		return mUtils.transactSetLong(METHOD_SET_MASTER_ELECTION_GROUP_ID, id);
		}

		/**
		* Gets the name of the network interface which the common time service attempts to bind to.
		*
		* @return a string with the network interface name which the common time service is bound to,
		* or null if the service is currently unbound. Examples of interface names are things like
		* "eth0", or "wlan0".
		* @throws android.os.RemoteException
		*/
		public String getInterfaceBinding()
		throws RemoteException {
		throwOnDeadServer();

		String ifaceName = mUtils.transactGetString(METHOD_GET_INTERFACE_BINDING, null);

		if ((null != ifaceName) && (0 == ifaceName.length()))
		return null;

		return ifaceName;
		}

		/**
		* Sets the name of the network interface which the common time service should attempt to bind
		* to.
		*
		* @param ifaceName The name of the network interface ("eth0", "wlan0", etc...) wich the common
		* time service should attempt to bind to, or null to force the common time service to unbind
		* from the network and run in networkless mode.
		* @return {@link #SUCCESS} in case of success,
		* {@link #ERROR}, {@link #ERROR_BAD_VALUE} or {@link #ERROR_DEAD_OBJECT} in case of failure.
		*/
		public int setNetworkBinding(String ifaceName) {
		if (checkDeadServer())
		return ERROR_DEAD_OBJECT;

		return mUtils.transactSetString(METHOD_SET_INTERFACE_BINDING,
		(null == ifaceName) ? "" : ifaceName);
		}

		/**
		* Gets the amount of time the common time service will wait between master announcements when
		* it is the timeline master.
		*
		* @return The time (in milliseconds) between master announcements.
		* @throws android.os.RemoteException
		*/
		public int getMasterAnnounceInterval()
		throws RemoteException {
		throwOnDeadServer();
		return mUtils.transactGetInt(METHOD_GET_MASTER_ANNOUNCE_INTERVAL, -1);
		}

		/**
		* Sets the amount of time the common time service will wait between master announcements when
		* it is the timeline master.
		*
		* @param interval The time (in milliseconds) between master announcements.
		* @return {@link #SUCCESS} in case of success,
		* {@link #ERROR}, {@link #ERROR_BAD_VALUE} or {@link #ERROR_DEAD_OBJECT} in case of failure.
		*/
		public int setMasterAnnounceInterval(int interval) {
		if (checkDeadServer())
		return ERROR_DEAD_OBJECT;
		return mUtils.transactSetInt(METHOD_SET_MASTER_ANNOUNCE_INTERVAL, interval);
		}

		/**
		* Gets the amount of time the common time service will wait between time synchronization
		* requests when it is the client of another common time service on the network.
		*
		* @return The time (in milliseconds) between time sync requests.
		* @throws android.os.RemoteException
		*/
		public int getClientSyncInterval()
		throws RemoteException {
		throwOnDeadServer();
		return mUtils.transactGetInt(METHOD_GET_CLIENT_SYNC_INTERVAL, -1);
		}

		/**
		* Sets the amount of time the common time service will wait between time synchronization
		* requests when it is the client of another common time service on the network.
		*
		* @param interval The time (in milliseconds) between time sync requests.
		* @return {@link #SUCCESS} in case of success,
		* {@link #ERROR}, {@link #ERROR_BAD_VALUE} or {@link #ERROR_DEAD_OBJECT} in case of failure.
		*/
		public int setClientSyncInterval(int interval) {
		if (checkDeadServer())
		return ERROR_DEAD_OBJECT;
		return mUtils.transactSetInt(METHOD_SET_CLIENT_SYNC_INTERVAL, interval);
		}

		/**
		* Gets the panic threshold for the estimated error level of the common time service. When the
		* common time service's estimated error rises above this level, the service will panic and
		* reset, causing a discontinuity in the currently synchronized timeline.
		*
		* @return The threshold (in microseconds) past which the common time service will panic.
		* @throws android.os.RemoteException
		*/
		public int getPanicThreshold()
		throws RemoteException {
		throwOnDeadServer();
		return mUtils.transactGetInt(METHOD_GET_PANIC_THRESHOLD, -1);
		}

		/**
		* Sets the panic threshold for the estimated error level of the common time service. When the
		* common time service's estimated error rises above this level, the service will panic and
		* reset, causing a discontinuity in the currently synchronized timeline.
		*
		* @param threshold The threshold (in microseconds) past which the common time service will
		* panic.
		* @return {@link #SUCCESS} in case of success,
		* {@link #ERROR}, {@link #ERROR_BAD_VALUE} or {@link #ERROR_DEAD_OBJECT} in case of failure.
		*/
		public int setPanicThreshold(int threshold) {
		if (checkDeadServer())
		return ERROR_DEAD_OBJECT;
		return mUtils.transactSetInt(METHOD_SET_PANIC_THRESHOLD, threshold);
		}

		/**
		* Gets the current state of the common time service's auto disable flag.
		*
		* @return The current state of the common time service's auto disable flag.
		* @throws android.os.RemoteException
		*/
		public boolean getAutoDisable()
		throws RemoteException {
		throwOnDeadServer();
		return (1 == mUtils.transactGetInt(METHOD_GET_AUTO_DISABLE, 1));
		}

		/**
		* Sets the current state of the common time service's auto disable flag. When the time
		* service's auto disable flag is set, it will automatically cease all network activity when
		* it has no active local clients, resuming activity the next time the service has interested
		* local clients. When the auto disabled flag is cleared, the common time service will continue
		* to participate the time synchronization group even when it has no active local clients.
		*
		* @param autoDisable The desired state of the common time service's auto disable flag.
		* @return {@link #SUCCESS} in case of success,
		* {@link #ERROR} or {@link #ERROR_DEAD_OBJECT} in case of failure.
		*/
		public int setAutoDisable(boolean autoDisable) {
		if (checkDeadServer())
		return ERROR_DEAD_OBJECT;

		return mUtils.transactSetInt(METHOD_SET_AUTO_DISABLE, autoDisable ? 1 : 0);
		}

		/**
		* At startup, the time service enters the initial state and remains there until it is given a
		* network interface to bind to. Common time will be unavailable to clients of the common time
		* service until the service joins a network (even an empty network). Devices may use the
		* {@link #forceNetworklessMasterMode()} method to force a time service in the INITIAL state
		* with no network configuration to assume MASTER status for a brand new timeline in order to
		* allow clients of the common time service to operate, even though the device is isolated and
		* not on any network. When a networkless master does join a network, it will defer to any
		* masters already on the network, or continue to maintain the timeline it made up during its
		* networkless state if no other masters are detected. Attempting to force a client into master
		* mode while it is actively bound to a network will fail with the status code {@link #ERROR}
		*
		* @return {@link #SUCCESS} in case of success,
		* {@link #ERROR} or {@link #ERROR_DEAD_OBJECT} in case of failure.
		*/
		public int forceNetworklessMasterMode() {
		android.os.Parcel data = android.os.Parcel.obtain();
		android.os.Parcel reply = android.os.Parcel.obtain();

		try {
		data.writeInterfaceToken(mInterfaceDesc);
		mRemote.transact(METHOD_FORCE_NETWORKLESS_MASTER_MODE, data, reply, 0);

		return reply.readInt();
		}
		catch (RemoteException e) {
		return ERROR_DEAD_OBJECT;
		}
		finally {
		reply.recycle();
		data.recycle();
		}
		}

		/**
		* The OnServerDiedListener interface defines a method called by the
		* {@link android.os.CommonTimeConfig} instance to indicate that the connection to the native
		* media server has been broken and that the {@link android.os.CommonTimeConfig} instance will
		* need to be released and re-created. The client application can implement this interface and
		* register the listener with the {@link #setServerDiedListener(OnServerDiedListener)} method.
		*/
		public interface OnServerDiedListener {
		/**
		* Method called when the native common time service has died. <p>If the native common time
		* service encounters a fatal error and needs to restart, the binder connection from the
		* {@link android.os.CommonTimeConfig} instance to the common time service will be broken.
		*/
		void onServerDied();
		}

		/**
		* Registers an OnServerDiedListener interface.
		* <p>Call this method with a null listener to stop receiving server death notifications.
		*/
		public void setServerDiedListener(OnServerDiedListener listener) {
		synchronized (mListenerLock) {
		mServerDiedListener = listener;
		}
		}

		protected void finalize() throws Throwable { release(); }

		private boolean checkDeadServer() {
		return ((null == mRemote) \|\| (null == mUtils));
		}

		private void throwOnDeadServer() throws RemoteException {
		if (checkDeadServer())
		throw new RemoteException();
		}

		private final Object mListenerLock = new Object();
		private OnServerDiedListener mServerDiedListener = null;

		private IBinder mRemote = null;
		private String mInterfaceDesc = "";
		private CommonTimeUtils mUtils;

		private IBinder.DeathRecipient mDeathHandler = new IBinder.DeathRecipient() {
		public void binderDied() {
		synchronized (mListenerLock) {
		if (null != mServerDiedListener)
		mServerDiedListener.onServerDied();
		}
		}
		};

		private static final int METHOD_GET_MASTER_ELECTION_PRIORITY = IBinder.FIRST_CALL_TRANSACTION;
		private static final int METHOD_SET_MASTER_ELECTION_PRIORITY = METHOD_GET_MASTER_ELECTION_PRIORITY + 1;
		private static final int METHOD_GET_MASTER_ELECTION_ENDPOINT = METHOD_SET_MASTER_ELECTION_PRIORITY + 1;
		private static final int METHOD_SET_MASTER_ELECTION_ENDPOINT = METHOD_GET_MASTER_ELECTION_ENDPOINT + 1;
		private static final int METHOD_GET_MASTER_ELECTION_GROUP_ID = METHOD_SET_MASTER_ELECTION_ENDPOINT + 1;
		private static final int METHOD_SET_MASTER_ELECTION_GROUP_ID = METHOD_GET_MASTER_ELECTION_GROUP_ID + 1;
		private static final int METHOD_GET_INTERFACE_BINDING = METHOD_SET_MASTER_ELECTION_GROUP_ID + 1;
		private static final int METHOD_SET_INTERFACE_BINDING = METHOD_GET_INTERFACE_BINDING + 1;
		private static final int METHOD_GET_MASTER_ANNOUNCE_INTERVAL = METHOD_SET_INTERFACE_BINDING + 1;
		private static final int METHOD_SET_MASTER_ANNOUNCE_INTERVAL = METHOD_GET_MASTER_ANNOUNCE_INTERVAL + 1;
		private static final int METHOD_GET_CLIENT_SYNC_INTERVAL = METHOD_SET_MASTER_ANNOUNCE_INTERVAL + 1;
		private static final int METHOD_SET_CLIENT_SYNC_INTERVAL = METHOD_GET_CLIENT_SYNC_INTERVAL + 1;
		private static final int METHOD_GET_PANIC_THRESHOLD = METHOD_SET_CLIENT_SYNC_INTERVAL + 1;
		private static final int METHOD_SET_PANIC_THRESHOLD = METHOD_GET_PANIC_THRESHOLD + 1;
		private static final int METHOD_GET_AUTO_DISABLE = METHOD_SET_PANIC_THRESHOLD + 1;
		private static final int METHOD_SET_AUTO_DISABLE = METHOD_GET_AUTO_DISABLE + 1;
		private static final int METHOD_FORCE_NETWORKLESS_MASTER_MODE = METHOD_SET_AUTO_DISABLE + 1;
		}