org.ocap.media
Class MediaAccessHandlerRegistrar

java.lang.Object
  extended by org.ocap.media.MediaAccessHandlerRegistrar

public abstract class MediaAccessHandlerRegistrar
extends Object

This class allows an application to block presentation of A/V content based on program content rating signaling or by specification of BlockedServices. It also allows an application to register an application-provided MediaAccessHandler to block presentation. This class also allows overriding (disabling/enabling) of blocking settings.


Method Summary
static MediaAccessHandlerRegistrar getInstance()
          This method returns the sole instance of the MediaAccessHandlerRegistrar class.
abstract  boolean getNotifyCondition()
          Gets the MediaAccessHandler notify condition set by the setNotifyCondition method.
abstract  boolean getNotRatedSignalBlocking(int rating)
          Gets blocking setting for TV blocking rating TV_NONE or movie blocking rating MPAA_NOT_RATED.
abstract  boolean getServiceBlockingOverride(int level)
          Gets the service blocking override for a specific level.
abstract  int getSignaledBlocking()
          Gets the signaled rating blocking value set by setSignaledBlocking or the default defined by that method.
abstract  boolean getSignaledBlockingOverride()
          Gets the signaled blocking override.
abstract  void grantMediaAccessAuthorization(Service service)
          Grants media access authorization for a service by removing presentation denial caused by a previous call to MediaAccessHandler.checkMediaAccessAuthorization(boolean, org.ocap.net.OcapLocator[]) for all components in a service.
abstract  void registerMediaAccessHandler(MediaAccessHandler mah)
          Registers the handler that can prevent the presentation of A/V service components.
abstract  void removeServiceBlocking(BlockedService[] blockedServices)
          Removes services to be blocked that were set by the setServiceBlocking method.
abstract  void setNotifyCondition(boolean notifyMediaAccessHandler)
          Sets the implementation behavior for services that have not been blocked for any parental rating reason.
abstract  void setNotRatedSignaledBlocking(int rating, boolean block)
          Sets blocking for TV blocking rating TV_NONE or movie blocking rating MPAA_NOT_RATED.
abstract  void setServiceBlocking(BlockedService[] blockedServices)
          Sets services to be blocked.
abstract  void setServiceBlockingOverride(int startLevel, int endLevel, boolean action)
          Sets service blocking override on or off, based on the level associated with a BlockedService.
abstract  void setSignaledBlocking(int rating)
          Sets parental control blocking based on VBI parental control or content_advisory_descriptor signaling.
abstract  void setSignaledBlockingOverride(boolean action)
          Sets signaled blocking override on or off.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getInstance

public static MediaAccessHandlerRegistrar getInstance()
This method returns the sole instance of the MediaAccessHandlerRegistrar class. The MediaAccessHandlerRegistrar instance is a singleton.

Returns:
The MediaAccessHandlerRegistrar instance.

registerMediaAccessHandler

public abstract void registerMediaAccessHandler(MediaAccessHandler mah)
Registers the handler that can prevent the presentation of A/V service components.

At most, only one instance of MediaAccessHandler can be set. Multiple calls of this method replace the previous instance by a new one. By default, no MediaAccessHandler is set, in which case the MediaAccessHandler.checkMediaAccessAuthorization() method is not called.

Parameters:
mah - The MediaAccessHandler to register. If null, the MediaAccessHandler instance will be removed.
Throws:
SecurityException - if the caller does not have MonitorAppPermission("mediaAccess") permission.
See Also:
MediaAccessHandler

setSignaledBlocking

public abstract void setSignaledBlocking(int rating)
Sets parental control blocking based on VBI parental control or content_advisory_descriptor signaling. This method MAY be used to set separate blocking for TV and movie ratings. The constants in the ParentalControlRatings interface provide legal values for the rating parameter. The values for TV and MPAA ratings can be OR'ed together to set both rating types at the same time. A non-zero value for either rating type will over-write the value for that rating type. A zero value for either rating type will not change the value of that rating type.

This method will not block the TV_NONE or MPAA_NOT_RATED ratings. Blocking not rated programs can be accomplished with the setSignaledNotRatedBlocking method. The default setting for the TV ratings is TV_NONE and for the movie ratings is MPAA_NA. Setting the default values will turn off all rated and signaled blocking.

When this method is called, the implementation SHALL re-evaluate blocking for immediate effect on all presenting services.

Parameters:
rating - The rating to set blocking at. This can be a TV_* constant or an MPAA_* constant, or both, ORed together.
Throws:
SecurityException - if the caller does not have MonitorAppPermission("mediaAccess") permission.
IllegalArgumentException - if rating is not equal to one of the constant values in ParentalControlRatings constants, or if rating is not equal to two of the constant values OR'ed together. If two of the constants are OR'ed together and both are TV_* or both are MPAA_* constants. If more than two of the constants are OR'ed together.

getSignaledBlocking

public abstract int getSignaledBlocking()
Gets the signaled rating blocking value set by setSignaledBlocking or the default defined by that method. The value returned is the TV rating blocking value OR'ed together with the MPAA rating blocking value. The TV and MPAA rating blocking values can be seen in ParentalControlRatings.

Returns:
The TV and movie rating blocking values.

setSignaledBlockingOverride

public abstract void setSignaledBlockingOverride(boolean action)
Sets signaled blocking override on or off. Setting the override to on SHALL over-ride all parental rating blocking that have been set by calls to the setSignaledBlocking or setNotRatedSignaledBlocking methods. This does not modifying a setting made by that method. Setting the override to off SHALL restore parental blocking. Override is off by default.

When this method is called, the implementation SHALL re-evaluate blocking for immediate effect on all presenting services.

Parameters:
action - When true, sets override on; otherwise, sets override off.
Throws:
SecurityException - if the caller does not have MonitorAppPermission("mediaAccess") permission.

getSignaledBlockingOverride

public abstract boolean getSignaledBlockingOverride()
Gets the signaled blocking override.

Returns:
True if signaled blocking over-ride is on; otherwise, returns false.

setNotRatedSignaledBlocking

public abstract void setNotRatedSignaledBlocking(int rating,
                                                 boolean block)
Sets blocking for TV blocking rating TV_NONE or movie blocking rating MPAA_NOT_RATED. By default these ratings are not blocked. Regardless of rating blocking settings made by the setSignaledBlocking method, only the TV_NONE and MPAA_NOT_RATED ratings can be blocked by this method. When the block parameter is true for a not rated rating, indicated by the rating parameter, not rated programs signaled with that rating via VBI parental control or content_advisory_descriptor signaling SHALL be blocked. This method SHALL NOT affect blocking of programs with any other parental control rating.

When this method is called, the implementation SHALL re-evaluate blocking for immediate effect on all presenting services.

Parameters:
rating - Can be a value of ParentalControlRatings.TV_NONE or ParentalControlRatings.MPAA_NOT_RATED.
block - When set to true will block, otherwise will unblock.
Throws:
IllegalArgumentException - if the rating parameter is not TV_NONE or MPAA_NOT_RATED.
SecurityException - if the caller does not have MonitorAppPermission("mediaAccess") permission.

getNotRatedSignalBlocking

public abstract boolean getNotRatedSignalBlocking(int rating)
Gets blocking setting for TV blocking rating TV_NONE or movie blocking rating MPAA_NOT_RATED.

Parameters:
rating - Can be a value of ParentalControlRatings.TV_NONE or ParentalControlRatings.MPAA_NOT_RATED.
Returns:
True if the parameter rating is currently blocked, otherwise returns false.
Throws:
IllegalArgumentException - if the rating parameter is not TV_NONE or MPAA_NOT_RATED.

setServiceBlocking

public abstract void setServiceBlocking(BlockedService[] blockedServices)
Sets services to be blocked. If the start time of a blocked service entry in the parameter has a duration in the past and the corresponding content is not in a buffer the entry MAY be ignored. The implementation SHALL evaluate the parameter for immediate effect on all presenting services.

Throws:
SecurityException - if the caller does not have MonitorAppPermission("mediaAccess") permission.

setServiceBlockingOverride

public abstract void setServiceBlockingOverride(int startLevel,
                                                int endLevel,
                                                boolean action)
Sets service blocking override on or off, based on the level associated with a BlockedService. Setting the override to on SHALL override all parental rating blocking that have been set by calls to the setServiceBlocking method for a specific set of levels. This includes all levels equal to and in between the startLevel and endLevel parameters. This does not modify a settings made by the setServiceBlocking method. Setting the override to off SHALL restore parental blocking for the set of levels. All override values are set to false before evaluating the parameters. Override is turned off completely by passing a false action and any start and end levels. Override is off by default for all levels.

When this method is called, the implementation SHALL re-evaluate blocking for immediate effect on all presenting services.

Parameters:
startLevel - The first level in the set of levels to override.
endLevel - The last level in the set of levels to override.
action - When true sets over-ride on, otherwise sets override off.
Throws:
SecurityException - if the caller does not have MonitorAppPermission("mediaAccess") permission.

getServiceBlockingOverride

public abstract boolean getServiceBlockingOverride(int level)
Gets the service blocking override for a specific level.

Parameters:
level - The level to get override blocking for.
Returns:
True if service blocking override is on for the level; otherwise, returns false.

removeServiceBlocking

public abstract void removeServiceBlocking(BlockedService[] blockedServices)
Removes services to be blocked that were set by the setServiceBlocking method. If an entry in the blocked services parameter is not currently blocked it MAY be ignored. The implementation SHALL evaluate the parameter for immediate effect on all presenting services.

Throws:
SecurityException - if the caller does not have MonitorAppPermission("mediaAccess") permission.

setNotifyCondition

public abstract void setNotifyCondition(boolean notifyMediaAccessHandler)
Sets the implementation behavior for services that have not been blocked for any parental rating reason. The default behavior is a registered MediaAccessHandler is notified and the implementation SHALL call the checkMediaAccessAuthorization method in that case. When the notifyMediaAccessHandler parameter is false it indicates the MediaAccessHandler is not to be informed when a service that is not blocked is selected or changes.

Parameters:
notifyMediaAccessHandler - When true indicates a registered MediaAccessHandler SHALL be informed when service component presentation changes and the service has not been blocked; otherwise, a registered MediaAccessHandler is not informed.
Throws:
SecurityException - if the caller does not have MonitorAppPermission("mediaAccess") permission.

getNotifyCondition

public abstract boolean getNotifyCondition()
Gets the MediaAccessHandler notify condition set by the setNotifyCondition method.

Returns:
Value set by the setNotifyCondition method. If the setNotifyCondition method has not been called this method returns the default value of true.

grantMediaAccessAuthorization

public abstract void grantMediaAccessAuthorization(Service service)
Grants media access authorization for a service by removing presentation denial caused by a previous call to MediaAccessHandler.checkMediaAccessAuthorization(boolean, org.ocap.net.OcapLocator[]) for all components in a service. If any component in the Service parameter was not denied by a previous call to checkMediaAccessAuthorization this method does nothing successfully. This method does not affect blocking setup by other MediaAccessHandlerRegistrar methods.

Parameters:
service - The service to grant access to.