1 /*---------------------------------------------------------------------------* 2 3 Copyright (C) 2012 Nintendo. All rights reserved. 4 5 These coded instructions, statements, and computer programs contain 6 proprietary information of Nintendo of America Inc. and/or Nintendo 7 Company Ltd., and are protected by Federal copyright law. They may 8 not be disclosed to third parties or copied or duplicated in any form, 9 in whole or in part, without the prior written consent of Nintendo. 10 11 *---------------------------------------------------------------------------*/ 12 13 #ifndef NN_NGC_CAFE_PROFANITY_FILTER_H_ 14 #define NN_NGC_CAFE_PROFANITY_FILTER_H_ 15 16 #include <nn/ngc/CAFE/ngc_ProfanityFilterPatternList.h> 17 #include <nn/ngc/CAFE/ngc_ProfanityFilterBase.h> 18 19 #if !defined( NN_NGC_CAFE_PROFANITY_FILTER_PATTERN_LIST_H_ ) || !defined( NN_NGC_CAFE_PROFANITY_FILTER_BASE_H_ ) 20 # error include error 21 #endif 22 23 namespace nn 24 { 25 namespace ngc 26 { 27 namespace Cafe 28 { 29 30 /*! 31 @addtogroup nn_ngc_api 32 @{ 33 */ 34 35 /*! 36 @brief Contains functions for profanity filtering. 37 38 You can use this class to check a user input string against the profanity list installed on the system, and determine whether it contains profanity. 39 For instructions on when to perform profanity filtering in your application, see the latest UGC Guidelines. 40 This library has the same functionality as the DWC library for the Wii, but by using this library you can check for profanity without working through a server. 41 42 A test profanity list is registered for each language and region. 43 Use a test string to make sure that the profanity library is properly embedded. 44 For more information, see the documentation of the <tt>nn::ngc::Cafe::ProfanityFilterPatternList</tt> enumerated type. 45 46 This class is not thread-safe. Operation is undefined if you access an instance of this class from multiple threads. 47 48 49 50 */ 51 class ProfanityFilter : public ProfanityFilterBase 52 { 53 public: 54 55 /*! 56 @brief Instantiates the object without performing initialization. 57 58 Initialization must occur before this class can be used. 59 */ 60 explicit ProfanityFilter(); 61 62 /*! 63 @brief Instantiates the object and initializes it. 64 65 The specified memory region is used as the working area. 66 Do not write any data to this working area, or release the area while it is in use. 67 The application must manage the specified memory area. The class does not free the memory when it is done using it. 68 You must allocate at least <tt>ProfanityFilter::WORKMEMORY_SIZE</tt> bytes of memory. 69 70 @param[in] pWorkMemory Specifies a pointer to the start of the working memory region. 71 72 */ ProfanityFilter(uptr pWorkMemory)73 explicit ProfanityFilter( uptr pWorkMemory ) { Initialize( pWorkMemory ); } 74 75 /*! 76 @brief Finalizes the class instance. 77 */ ~ProfanityFilter()78 virtual ~ProfanityFilter(){ Finalize(); } 79 80 /*! 81 @brief Initializes the profanity filtering class. 82 83 The specified memory region is used as the working area. 84 Do not write any data to this working area, or release the area while it is in use. 85 The application must manage the specified memory area. The class does not free the memory when it is done using it. 86 You must allocate at least <tt>ProfanityFilter::WORKMEMORY_SIZE</tt> bytes of memory. 87 88 @param[in] pWorkMemory Specifies a pointer to the start of the working memory region. 89 90 @return Returns the result of execution. The following values are returned. 91 @retval nn::ResultSuccess Indicates that initialization succeeded. 92 @retval ResultInvalidPointer Indicates an invalid pointer. 93 @retval ResultMountContentsFailed Indicates failure to prepare to load the profanity filter. This error is not returned on a normally functioning system. 94 95 */ 96 nn::Result Initialize( uptr pWorkMemory ); 97 98 void SkipAtSignCheck( bool bSkipChecking ); 99 100 /*! 101 @brief Ends the use of the profanity filtering class. 102 103 @return Returns the result of execution. The following values are returned. 104 @retval nn::ResultSuccess Indicates success. 105 */ 106 nn::Result Finalize(); 107 108 /*! 109 @brief Gets the version number of the profanity pattern file currently installed on the system. 110 @return The version number. Versions begin from 1, with higher numbers indicating newer versions. Returns <tt>0</tt> if the attempt to get the value fails. 111 */ 112 virtual u32 GetContentVersion(); 113 114 /*! 115 @brief Checks a number of specified words against the specified pattern list and the pattern list specified in the UGC Guidelines to determine whether strings contain profanity and should not be displayed. 116 117 This function checks single words, such as screen names. 118 It cannot be used to process text added by the user. 119 To check text input, use the <tt>@ref ProfanityFilter::MaskProfanityWordsInText</tt> function instead. 120 121 This operation may take a long time. (It blocks.) Processing time can vary depending on such factors as the version of the system and the length of the specified string. 122 We recommend running this function in a separate thread. Running it in the main thread can cause the frame rate to decrease. 123 You can use this function to check a maximum of <tt>@ref nn::ngc::MAX_WORD_NUM</tt> strings at one time. 124 Checking multiple strings at the same time requires less time than checking each string separately. 125 126 The results of the check on each string are stored in the <span class="argument">pCheckResults</span> array. 127 Check by taking the bitwise AND of this array and the result of left-shifting the value <tt>1</tt> by the value specified in <span class="argument">nPatterns</span>. 128 The bit field has a value of <tt>0</tt> if there are no profanity patterns specified in any pattern lists. 129 130 The at symbol ("@") could denote an email address. The function always detects strings containing this character as possible disallowed words. However, it does not detect strings containing lots of numbers as problematic, although such strings could be used to display telephone numbers or other sensitive information. 131 Use the <tt>@ref nn::ngc::Cafe::CountNumbers</tt> function to check for this. 132 133 @param[out] pCheckResults Specifies the buffer that stores the results of the check. This parameter requires an array with <span class="argument">nWordCount</span> elements. 134 @param[in] nPatterns Specifies a pattern list, in addition to the pattern list specified in the UGC Guidelines. 135 Left shift <tt>1</tt> by the pattern values in <tt>nn::ngc::Cafe::ProfanityFilterPatternList</tt>. 136 Use a bitwise OR when making multiple specifications. 137 This specified pattern is ignored when specifying a pattern list specified in the UGC Guidelines. 138 Specify <tt>0</tt> when not adding a pattern list. 139 @param[in] ppWords Specifies a <tt>NULL</tt>-terminated string array containing the words to check. Use UTF16-BE (big-endian) encoding. 140 @param[in] nWordCount Specifies the number of strings to check. The maximum number is <tt>@ref nn::ngc::MAX_WORD_NUM</tt>. 141 142 @return Returns the result of the function. The following values are returned. 143 @retval nn::ResultSuccess Indicates that the check succeeded. 144 @retval ResultNotInitialized Indicates the object was not initialized. 145 @retval ResultInvalidPointer Indicates an invalid pointer. 146 @retval ResultInvalidSize Indicates that the specified number of strings is invalid. 147 @retval ResultReadContentsFailed Indicates a failure to load the profanity filter. This error is not returned on a normally functioning system. 148 149 150 151 */ 152 virtual nn::Result CheckProfanityWords( bit32* pCheckResults, bit32 nPatterns, const wchar_t** ppWords, size_t nWordCount ); 153 154 /*! 155 @brief Configures how to respond when text is checked and profanity is discovered. 156 157 In the default mode, the entire text is overwritten with asterisk symbols when profanity is discovered. In some cases, this can result in display of text outside of the area of the box on the screen. 158 For example, the asterisk symbol ("*") is wider than the letter "i" when a proportional font is used. When overwriting the text with asterisk symbols, there is a risk that the result will extend beyond the screen. 159 160 By specifying <tt>false</tt> for this function, only one asterisk is displayed in substitution for a profanity word, regardless of the number of characters in the profanity word. As a result, there is no danger to the integrity of the user interface. 161 162 This setting is only enabled when text is checked using the <tt>ProfanityFilter::MaskProfanityWordsInText</tt> function. 163 It has no effect on operations when words are being checked by the <tt>@ref ProfanityFilter::CheckProfanityWords</tt> function. 164 165 The specified setting is reset to the default state (<tt>true</tt>) when the <tt>@ref ProfanityFilter::Finalize</tt> function is called. 166 167 @param[in] bOverWrite Specify <tt>true</tt> (the default setting) to overwrite the entire text with asterisk symbols when profanity is discovered. 168 Specify <tt>false</tt> to substitute a single asterisk symbol for any discovered profanity word. 169 170 171 172 173 */ 174 void SetMaskMode( bool bOverWrite ); 175 176 /*! 177 @brief Checks the specified text against the specified pattern list and the pattern list specified in the UGC Guidelines to determine whether strings contain profanity and should not be displayed. 178 179 180 This function processes text strings equal to or longer than a particular length. 181 It cannot process short single words, such as screen names. 182 To check words, use the <tt>@ref ProfanityFilter::CheckProfanityWords</tt> function instead. 183 184 When this function is called, it checks specified strings to determine whether they contain profanity and masks those parts with asterisks (*). 185 186 This operation may take a long time. (It blocks.) Processing time may vary depending on such factors as the version of the system and the length of the specified string. 187 We recommend running this function in a separate thread. Running it in the main thread can cause the frame rate to decrease. 188 189 @param[out] pProfanityWordCount Specifies a pointer to the number of times profanity appeared in a text. If this information is not required, you can specify <tt>NULL</tt>. 190 @param[in] nPatterns Specifies a pattern list, in addition to the pattern list specified in the UGC Guidelines. 191 Left shift <tt>1</tt> by the pattern values in <tt>nn::ngc::Cafe::ProfanityFilterPatternList</tt>. 192 Use a bitwise OR when making multiple specifications. 193 This specified pattern is ignored when specifying a pattern list specified in the UGC Guidelines. 194 Specify <tt>0</tt> when not adding a pattern list. 195 @param[in,out] pText Specifies the pointer to the text that is the subject of the <span class="argument">pText</span> check. Places where profanity appears in the text are overwritten by an asterisk. 196 For this reason, you must specify a buffer that the application can write to. 197 A maximum of <tt>@ref nn::ngc::MAX_TEXT_LENGTH</tt> characters, including the terminating null character, can be checked. If a string is longer than this, the part that exceeds this maximum length is not checked. 198 199 @return Returns the result of the function. The following values are returned. 200 @retval nn::ResultSuccess Indicates that the check succeeded. 201 @retval ResultNotInitialized Indicates the object was not initialized. 202 @retval ResultInvalidPointer Indicates an invalid pointer. 203 @retval ResultReadContentsFailed Indicates a failure to load the profanity filter. This error is not returned on a normally functioning system. 204 205 206 207 */ 208 virtual nn::Result MaskProfanityWordsInText( int* pProfanityWordCount, bit32 nPatterns, wchar_t* pText ); 209 210 211 public: 212 /*! 213 @brief Constant Declarations 214 */ 215 enum 216 { 217 //! The size of the memory region needed for checking. 218 WORKMEMORY_SIZE = 64 * 1024 219 }; 220 221 private: 222 void CleanUpVariables(); 223 void SetupMemoryArea(); 224 nn::Result MountSharedContents(); 225 226 nn::Result CheckArguments_Word( const bit32* pCheckResults, const wchar_t** ppWords, size_t nWordCount ) const; 227 nn::Result CheckProfanityWords_Impl( bit32* pCheckResults, const wchar_t** ppWords, size_t nWordCount ); 228 void CheckWords( bit32* pCheckResults, const wchar_t *pPattern, size_t nLength, wchar_t* const* ppConvertedWords, size_t nWordCount ); 229 230 nn::Result CheckArguments_Text( const wchar_t* pText ) const; 231 nn::Result MaskProfanityWordsInText_Impl( int* pProfanityWordCount, wchar_t* pUserInput, wchar_t* pConvertedUserInput, u8* pMapping); 232 void MaskText( int* pProfanityWordCount, wchar_t* pUserInput, wchar_t* pConvertedUserInput, u8* pMapping, const wchar_t* pPattern, bool bIgnoreSpace ); 233 234 private: 235 236 //! Indicates whether the content is mounted. 237 bool m_bContentMounted; 238 239 //! Whether to skip the at ("@") symbol. (The default is <tt>false</tt>.) 240 bool m_bSkipAtSignCheck; 241 242 //! Information currently being checked: the pattern list being checked against. 243 ProfanityFilterPatternList m_nPatternList; 244 245 //! Pointer to the start of the working memory area. 246 uptr m_pWorkingHead; 247 248 //! This area is used to convert a pattern list into an automaton. 249 uptr m_pTempPoolHead; 250 251 //! This area is used to store patterns loaded from NAND memory. 252 uptr m_pPatternsHead; 253 254 //! Working area used to mount shared content. 255 uptr m_pMountWorkingArea; 256 257 //! User area. (Its usage depends on whether word or long-text checking mode is being used). 258 uptr m_pUserArea; 259 260 //! Whether to overwrite masked strings when checking long text. (The default is <tt>true</tt>.) 261 bool m_bMaskOverWrite; 262 }; 263 264 //! @} 265 266 } // namespace Cafe 267 } // namespaec ngc 268 } // namespace nn 269 270 #endif // NN_NGC_CAFE_PROFANITY_FILTER_H_ 271