/* * Copyright (C) 2014 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.SystemApi; import android.text.TextUtils; import com.android.internal.util.Preconditions; import java.util.Arrays; import java.util.Collections; import java.util.List; import java.util.Objects; /** * A class representing a TV content rating. When a TV input service inserts the content rating * information on a program into the database, this class can be used to generate the formatted * string for * {@link TvContract.Programs#COLUMN_CONTENT_RATING TvContract.Programs.COLUMN_CONTENT_RATING}. * To create a {@code TvContentRating} object, use the * {@link #createRating TvContentRating.createRating} method with valid rating system string * constants. * *

It is possible for an application to define its own content rating system by supplying a * content rating system definition XML resource (see example below) and declaring a broadcast * receiver that filters {@link TvInputManager#ACTION_QUERY_CONTENT_RATING_SYSTEMS} in its manifest. * *

Example: Rating system definition for the TV Parental Guidelines

* The following XML example shows how the TV Parental Guidelines in the United States can be * defined: * 

 * {@literal
 * 
 *     
 *         
 *         
 *         
 *         
 *         
 *
 *         
 *         
 *             
 *         
 *         
 *         
 *             
 *             
 *             
 *             
 *         
 *         
 *             
 *             
 *             
 *             
 *         
 *         
 *             
 *             
 *             
 *         
 *         
 *             
 *             
 *         
 *         
 *             
 *             
 *             
 *             
 *         
 *     
 * }
* *

System defined rating strings

* The following strings are defined by the system to provide a standard way to create * {@code TvContentRating} objects. * *

For example, to create an object that represents TV-PG rating with suggestive dialogue and * coarse language from the TV Parental Guidelines in the United States, one can use the following * code snippet: * * 

 * TvContentRating rating = TvContentRating.createRating(
 *         "com.android.tv",
 *         "US_TV",
 *         "US_TV_PG",
 *         "US_TV_D", "US_TV_L");
 *
*

System defined string for domains

* * * * * * * * * *
Constant ValueDescription
com.android.tvUsed for creating system defined content ratings
* *

System defined strings for rating systems

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Constant ValueDescription
AR_TVTV content rating system for Argentina
AU_TVTV content rating system for Australia
BR_TVTV content rating system for Brazil
CA_TV_ENTV content rating system for Canada (English)
CA_TV_FRTV content rating system for Canada (French)
DVBDVB content rating system
ES_DVBDVB content rating system for Spain
FR_DVBDVB content rating system for France
ISDBISDB content rating system
KR_TVTV content rating system for South Korea
SG_TVTV content rating system for Singapore
US_MVMovie content rating system for the United States
US_TVTV content rating system for the United States
* *

System defined strings for ratings

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Rating SystemConstant ValueDescription
AR_TVAR_TV_ATPSuitable for all audiences. Programs may contain mild violence, language and mature * situations
AR_TV_SAM_13Suitable for ages 13 and up. Programs may contain mild to moderate language and mild * violence and sexual references
AR_TV_SAM_16Suitable for ages 16 and up. Programs may contain more intensive violence and coarse * language, partial nudity and moderate sexual references
AR_TV_SAM_18Suitable for mature audiences only. Programs contain strong violence, coarse language * and explicit sexual references
AU_TVAU_TV_PRecommended for younger children aged between 2 and 11 years
AU_TV_CRecommended for older children aged between 5 and 14 years
AU_TV_GRecommended for all ages
AU_TV_PGParental guidance is recommended for young viewers under 15
AU_TV_MRecommended for mature audiences aged 15 years and over
AU_TV_MANot suitable for children and teens under 15, due to sexual descriptions, course * language, adult themes or drug use
AU_TV_AVNot suitable for children and teens under 15. This category is used specifically for * violent programs
AU_TV_RNot for children under 18. Content may include graphic violence, sexual situations, * coarse language and explicit drug use
BR_TVBR_TV_LContent is suitable for all audiences
BR_TV_10Content suitable for viewers over the age of 10
BR_TV_12Content suitable for viewers over the age of 12
BR_TV_14Content suitable for viewers over the age of 14
BR_TV_16Content suitable for viewers over the age of 16
BR_TV_18Content suitable for viewers over the age of 18
CA_TV_ENCA_TV_EN_EXEMPTExempt from ratings
CA_TV_EN_CSuitable for children ages 2–7
CA_TV_EN_C8Suitable for children ages 8 and older
CA_TV_EN_GSuitable for the entire family
CA_TV_EN_PGMay contain moderate violence, profanity, nudity, and sexual references
CA_TV_EN_14Intended for viewers ages 14 and older
CA_TV_EN_18Intended for viewers ages 18 and older
CA_TV_FRCA_TV_FR_EExempt from ratings
CA_TV_FR_GAppropriate for all ages
CA_TV_FR_8Appropriate for children 8
CA_TV_FR_13Suitable for children 13
CA_TV_FR_16Recommended for children over the age of 16
CA_TV_FR_18Only to be viewed by adults
DVBDVB_4Recommended for ages 4 and over
DVB_5Recommended for ages 5 and over
DVB_6Recommended for ages 6 and over
DVB_7Recommended for ages 7 and over
DVB_8Recommended for ages 8 and over
DVB_9Recommended for ages 9 and over
DVB_10Recommended for ages 10 and over
DVB_11Recommended for ages 11 and over
DVB_12Recommended for ages 12 and over
DVB_13Recommended for ages 13 and over
DVB_14Recommended for ages 14 and over
DVB_15Recommended for ages 15 and over
DVB_16Recommended for ages 16 and over
DVB_17Recommended for ages 17 and over
DVB_18Recommended for ages 18 and over
ES_DVBES_DVB_ALLRecommended for all ages
ES_DVB_CRecommended for children
ES_DVB_XRecommended for adults
ES_DVB_4Recommended for ages 4 and over
ES_DVB_5Recommended for ages 5 and over
ES_DVB_6Recommended for ages 6 and over
ES_DVB_7Recommended for ages 7 and over
ES_DVB_8Recommended for ages 8 and over
ES_DVB_9Recommended for ages 9 and over
ES_DVB_10Recommended for ages 10 and over
ES_DVB_11Recommended for ages 11 and over
ES_DVB_12Recommended for ages 12 and over
ES_DVB_13Recommended for ages 13 and over
ES_DVB_14Recommended for ages 14 and over
ES_DVB_15Recommended for ages 15 and over
ES_DVB_16Recommended for ages 16 and over
ES_DVB_17Recommended for ages 17 and over
ES_DVB_18Recommended for ages 18 and over
FR_DVBFR_DVB_URecommended for all ages
FR_DVB_4Recommended for ages 4 and over
FR_DVB_5Recommended for ages 5 and over
FR_DVB_6Recommended for ages 6 and over
FR_DVB_7Recommended for ages 7 and over
FR_DVB_8Recommended for ages 8 and over
FR_DVB_9Recommended for ages 9 and over
FR_DVB_10Recommended for ages 10 and over
FR_DVB_11Recommended for ages 11 and over
FR_DVB_12Recommended for ages 12 and over
FR_DVB_13Recommended for ages 13 and over
FR_DVB_14Recommended for ages 14 and over
FR_DVB_15Recommended for ages 15 and over
FR_DVB_16Recommended for ages 16 and over
FR_DVB_17Recommended for ages 17 and over
FR_DVB_18Recommended for ages 18 and over
ISDBISDB_4Recommended for ages 4 and over
ISDB_5Recommended for ages 5 and over
ISDB_6Recommended for ages 6 and over
ISDB_7Recommended for ages 7 and over
ISDB_8Recommended for ages 8 and over
ISDB_9Recommended for ages 9 and over
ISDB_10Recommended for ages 10 and over
ISDB_11Recommended for ages 11 and over
ISDB_12Recommended for ages 12 and over
ISDB_13Recommended for ages 13 and over
ISDB_14Recommended for ages 14 and over
ISDB_15Recommended for ages 15 and over
ISDB_16Recommended for ages 16 and over
ISDB_17Recommended for ages 17 and over
ISDB_18Recommended for ages 18 and over
ISDB_19Recommended for ages 19 and over
ISDB_20Recommended for ages 20 and over
KR_TVKR_TV_ALLAppropriate for all ages
KR_TV_7May contain material inappropriate for children younger than 7, and parental * discretion should be used
KR_TV_12May deemed inappropriate for those younger than 12, and parental discretion should be * used
KR_TV_15May be inappropriate for children under 15, and that parental discretion should be * used
KR_TV_19For adults only
SG_TVSG_TV_GSuitable for all ages
SG_TV_PGSuitable for all but parents should guide their young
SG_TV_PG13Suitable for persons aged 13 and above but parental guidance is advised for children * below 13
SG_TV_NC16Suitable for persons aged 16 and above
SG_TV_M18Suitable for persons aged 18 and above
SG_TV_R21Suitable for adults aged 21 and above
US_MVUS_MV_GGeneral audiences
US_MV_PGParental guidance suggested
US_MV_PG13Parents strongly cautioned
US_MV_RRestricted, under 17 requires accompanying parent or adult guardian
US_MV_NC17No one 17 and under admitted
US_TVUS_TV_YThis program is designed to be appropriate for all children
US_TV_Y7This program is designed for children age 7 and above
US_TV_GMost parents would find this program suitable for all ages
US_TV_PGThis program contains material that parents may find unsuitable for younger children *
US_TV_14This program contains some material that many parents would find unsuitable for * children under 14 years of age
US_TV_MAThis program is specifically designed to be viewed by adults and therefore may be * unsuitable for children under 17
* *

System defined strings for sub-ratings

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Rating SystemConstant ValueDescription
BR_TVBR_TV_DDrugs
Applicable to BR_TV_L, BR_TV_10, BR_TV_12, BR_TV_14, BR_TV_16, and BR_TV_18 *
BR_TV_SSex
Applicable to BR_TV_L, BR_TV_10, BR_TV_12, BR_TV_14, BR_TV_16, and BR_TV_18 *
BR_TV_VViolence
Applicable to BR_TV_L, BR_TV_10, BR_TV_12, BR_TV_14, BR_TV_16, and * BR_TV_18
US_TVUS_TV_DSuggestive dialogue (Usually means talks about sex)
Applicable to US_TV_PG, and * US_TV_14
US_TV_LCoarse language
Applicable to US_TV_PG, US_TV_14, and US_TV_MA
US_TV_SSexual content
Applicable to US_TV_PG, US_TV_14, and US_TV_MA
US_TV_VViolence
Applicable to US_TV_PG, US_TV_14, and US_TV_MA
US_TV_FVFantasy violence (Children's programming only)
Applicable to US_TV_Y7
*/ public final class TvContentRating { // TODO: Consider to use other DELIMITER. In some countries such as India may use this delimiter // in the main ratings. private static final String DELIMITER = "/"; private final String mDomain; private final String mRatingSystem; private final String mRating; private final String[] mSubRatings; private final int mHashCode; /** * Rating constant denoting unrated content. Used to handle the case where the content rating * information is missing. * *

TV input services can call {@link TvInputManager#isRatingBlocked} with this constant to * determine whether they should block unrated content. The subsequent call to * {@link TvInputService.Session#notifyContentBlocked} with the same constant notifies * applications that the current program content is blocked by parental controls. */ public static final TvContentRating UNRATED = new TvContentRating("null", "null", "null", null); /** * Creates a {@code TvContentRating} object with predefined content rating strings. * * @param domain The domain string. For example, "com.android.tv". * @param ratingSystem The rating system string. For example, "US_TV". * @param rating The content rating string. For example, "US_TV_PG". * @param subRatings The sub-rating strings. For example, "US_TV_D" and "US_TV_L". * @return A {@code TvContentRating} object. * @throws IllegalArgumentException If {@code domain}, {@code ratingSystem} or {@code rating} is * {@code null}. */ public static TvContentRating createRating(String domain, String ratingSystem, String rating, String... subRatings) { if (TextUtils.isEmpty(domain)) { throw new IllegalArgumentException("domain cannot be empty"); } if (TextUtils.isEmpty(ratingSystem)) { throw new IllegalArgumentException("ratingSystem cannot be empty"); } if (TextUtils.isEmpty(rating)) { throw new IllegalArgumentException("rating cannot be empty"); } return new TvContentRating(domain, ratingSystem, rating, subRatings); } /** * Recovers a {@code TvContentRating} object from the string that was previously created from * {@link #flattenToString}. * * @param ratingString The string returned by {@link #flattenToString}. * @return the {@code TvContentRating} object containing the domain, rating system, rating and * sub-ratings information encoded in {@code ratingString}. * @see #flattenToString */ public static TvContentRating unflattenFromString(String ratingString) { if (TextUtils.isEmpty(ratingString)) { throw new IllegalArgumentException("ratingString cannot be empty"); } String[] strs = ratingString.split(DELIMITER); if (strs.length < 3) { throw new IllegalArgumentException("Invalid rating string: " + ratingString); } if (strs.length > 3) { String[] subRatings = new String[strs.length - 3]; System.arraycopy(strs, 3, subRatings, 0, subRatings.length); return new TvContentRating(strs[0], strs[1], strs[2], subRatings); } return new TvContentRating(strs[0], strs[1], strs[2], null); } /** * Constructs a TvContentRating object from a given rating and sub-rating constants. * * @param domain The string for domain of the content rating system such as "com.android.tv". * @param ratingSystem The rating system string such as "US_TV". * @param rating The content rating string such as "US_TV_PG". * @param subRatings The sub-rating strings such as "US_TV_D" and "US_TV_L". */ private TvContentRating( String domain, String ratingSystem, String rating, String[] subRatings) { mDomain = domain; mRatingSystem = ratingSystem; mRating = rating; if (subRatings == null || subRatings.length == 0) { mSubRatings = null; } else { Arrays.sort(subRatings); mSubRatings = subRatings; } mHashCode = 31 * Objects.hash(mDomain, mRating) + Arrays.hashCode(mSubRatings); } /** * Returns the domain of this {@code TvContentRating} object. */ public String getDomain() { return mDomain; } /** * Returns the rating system of this {@code TvContentRating} object. */ public String getRatingSystem() { return mRatingSystem; } /** * Returns the main rating of this {@code TvContentRating} object. */ public String getMainRating() { return mRating; } /** * Returns the unmodifiable sub-rating string {@link List} of this {@code TvContentRating} * object. */ public List getSubRatings() { if (mSubRatings == null) { return null; } return Collections.unmodifiableList(Arrays.asList(mSubRatings)); } /** * Returns a string that unambiguously describes the rating information contained in a * {@code TvContentRating} object. One can later recover the object from this string through * {@link #unflattenFromString}. * * @return a string containing the rating information, which can later be stored in the * database. * @see #unflattenFromString */ public String flattenToString() { StringBuilder builder = new StringBuilder(); builder.append(mDomain); builder.append(DELIMITER); builder.append(mRatingSystem); builder.append(DELIMITER); builder.append(mRating); if (mSubRatings != null) { for (String subRating : mSubRatings) { builder.append(DELIMITER); builder.append(subRating); } } return builder.toString(); } /** * Returns {@code true} if this rating has the same main rating as the specified rating and when * this rating's sub-ratings contain the other's. * *

For example, a {@code TvContentRating} object that represents TV-PG with * S(Sexual content) and V(Violence) contains TV-PG, TV-PG/S, TV-PG/V and itself. * * @param rating The {@link TvContentRating} to check. * @return {@code true} if this object contains {@code rating}, {@code false} otherwise. */ public final boolean contains(@NonNull TvContentRating rating) { Preconditions.checkNotNull(rating); if (!rating.getMainRating().equals(mRating)) { return false; } if (!rating.getDomain().equals(mDomain) || !rating.getRatingSystem().equals(mRatingSystem) || !rating.getMainRating().equals(mRating)) { return false; } List subRatings = getSubRatings(); List subRatingsOther = rating.getSubRatings(); if (subRatings == null && subRatingsOther == null) { return true; } else if (subRatings == null && subRatingsOther != null) { return false; } else if (subRatings != null && subRatingsOther == null) { return true; } else { return subRatings.containsAll(subRatingsOther); } } @Override public boolean equals(Object obj) { if (!(obj instanceof TvContentRating)) { return false; } TvContentRating other = (TvContentRating) obj; if (mHashCode != other.mHashCode) { return false; } if (!TextUtils.equals(mDomain, other.mDomain)) { return false; } if (!TextUtils.equals(mRatingSystem, other.mRatingSystem)) { return false; } if (!TextUtils.equals(mRating, other.mRating)) { return false; } return Arrays.equals(mSubRatings, other.mSubRatings); } @Override public int hashCode() { return mHashCode; } }