A data store is a storage service that provides features to manipulate arbitrary data, including uploading, downloading, updating, and deleting. Data is uploaded to data stores on game servers, in addition to dedicated storage servers. There are two ways to use data stores: using just the game server, or a redundant method that uses the game server in conjunction with the storage server. The application must choose which method to use when uploading data. Following are the advantages and disadvantages of each method.
Advantage: Processing is performed quickly because the processing completes by accessing the game server only.
Disadvantage: The maximum data size that can be uploaded is 1024 bytes.
Advantage: The maximum data size that can be uploaded is 10 megabytes. You can use the game server data area (meta binary), the storage server data area, or both. If you use both, you can upload any large data to the storage server, while storing items such as titles and authors that are accessed frequently, or multiple items that are retrieved as a batch process and displayed, such as by calling the DataStoreClient::SearchObject
function, on the game server.
Disadvantage: Processing may take time because of HTTP access to the storage server, depending on the API, in addition to game server access.
Choose the method to use based on the size of the data that you will be uploading.
A data store uses the following overall flow.
Initialization and finalization of the DataStoreClient
object is the same as for the matchmaking service client. However, you must initialize and finalize the HTTP library when you use the storage server. For more information, see Code 6.1 Initializing and Finalizing the Data Store Client.
Code 6.1 Initializing and Finalizing the Data Store Client
// Log in to the game server.
LoginGameSevrer(pNgsFacade);
Credentials* pCredentials = pNgsFacade->GetCredentials();
// Initialize the HTTP library.
nn::http::Initialize();
// Create a ServiceClient instance for each login attempt.
DataStoreClient* pDataStoreClient = qNew DataStoreClient();
pDataStoreClient->Bind(pCredentials);
// Do the processing.
pDataStoreClient->DoSomething();
// Unbind and destroy the object before logging out.
pDataStoreClient->Unbind();
qDelete pDataStoreClient;
// Log out from the game server, and then destroy the object.
LogoutGameServer(pNgsFacade)
qDelete pNgsFacade;
// Finalize the HTTP library.
nn::http::Finalize();
Use the DataStoreClient::PostObject
function to upload data. The following methods for uploading data are available.
Using only the game server
DataStorePostParam::SetMetaBinary
function of the DataStorePostParam
object. You must either not call DataStorePostParam::SetSize
and use the default value of 0
, or explicitly specify 0
.Using the game server and the storage server
Two upload methods are available.
Specify the data to upload in the buffer parameter, and set the size in the DataStorePostParam::SetSize
function of the DataStorePostParam
object.
Specify a class object that inherits DataStorePostObjectEventListener
and that overrides the DataStorePostObjectEventListener::PostChunkedBuffer
function in the eventListener parameter. Use this if you want to upload your data in chunks when you cannot allocate enough memory at one time.
If the upload succeeds, a unique ID identifying the uploaded data is stored in the dataId parameter. This ID is called the data ID. The parameters in Table 6.1 can be set with DataStorePostParam
as metadata for the data specified for uploading. The person who uploads the data becomes the owner, and the principal ID of the owner is registered in the server as the owner ID. Privileges and Passwords, Tags, Initializing Ratings, Meta-binaries, and Settings Flags are explained individually.
Note
There are a finite number of 64-bit data IDs. Used data IDs are also not reused after the data is deleted. Make sure that you do not use more than this number during the service period.
However, when you use Linking with SpotPass with CTR, the data ID is within a 32-bit range.
Also, your implementation must not assume the following.
This data has an expiration date that marks the end of its period of validity. When the uploaded data has expired, no operations on the data can be performed. Make sure to specify an appropriate period in your implementation that is long enough (maximum 365 days) so that deleting the data after it expires does not cause problems. Use the DataStorePostParam::SetPeriod
function for the specification. The expiration date may be extended by calling an API. For more information, see Changing Timestamp Values.
Name | Description | Initial Value | Settings Function |
---|---|---|---|
Size (Required) | The size of the data to upload. This value must match the actual size of the uploaded data. Note: You must set it to 0 when you are not using the storage server. |
0 | SetSize |
Name | The name of the data to upload. | Empty string | SetName |
Data type | The type of the data to upload. Use this value as a search condition with the DataStoreClient::SearchObject function. |
0 | SetDataType |
Access privileges | The scope of users who can access or search the data to upload. | DataStorePermission (DataStoreConstants:: PERMISSION_ PRIVATE ) |
SetAccessPermission |
Update permissions | Update permissions for the data to upload. | DataStorePermission (DataStoreConstants:: PERMISSION_ PRIVATE ) |
SetUpdatePermission |
Configuration flag | This function specifies the flags to set for the upload. | DataStoreConstants:: DATA_ FLAG_ NONE |
SetDataFlag |
The number of valid days | This function specifies the period (in days) during which uploaded data can be accessed. It can be up to 365 days. | DataStoreConstants::DEFAULT_PERIOD |
SetPeriod |
Tags | Tags to add to the data to upload. A maximum of DataStoreConstants:: tags can be specified. |
Empty | SetTags |
Initialization of rating slots | Initialization is required if you use rating features. Specify a slot number in the range from 0 to 15 for the map key, and the initialization parameters for each slot for the value. |
Empty | SetRatingSetting |
Meta-binary data | Binary data to store in the metadata. If you are using only the game server without using a storage server, store the data to be uploaded here. | Empty | SetMetaBinary |
Persistence setting | Set this parameter to perpetuate the data at the same time that it is uploaded. | DataStorePersistenceInitParam |
SetPersistenceInitParam |
Data types are application-defined values that represent different types of data. Specifying data types as a search condition when using the DataStoreClient::SearchObject
function allows you to filter by data type when searching objects. Categorizing data by data type improves search performance. Set the data type when you upload data to take advantage of this increase in search performance.
Note that uploading all data with a single data type results in a spike in game server load when searching that data. This can in turn lead to sluggish responses to search requests, and to an increased rate of failure when users attempt to log in to the game server.
You could also potentially use tags to categorize data, but depending on the type of data at hand, search responses can still sometimes be sluggish even when searching by tag. Nintendo strongly recommends using data types rather than tags to categorize data uploaded to the game server.
When you upload data, you can set the following five privilege types for both accessing and updating the data. Use the privilege type for such purposes as exchanging data with specific friends.
Privilege | Description |
---|---|
DataStoreConstants:: PERMISSION_ PUBLIC |
Grants permission to all principal IDs. |
DataStoreConstants:: PERMISSION_ FRIEND |
Only principal IDs of friends and the data owner have permissions. |
DataStoreConstants:: PERMISSION_ SPECIFIED |
Grants permission to the specified principal IDs. |
DataStoreConstants:: PERMISSION_ PRIVATE |
Grants permissions for the owner only. |
DataStoreConstants:: PERMISSION_ SPECIFIED_ FRIEND |
Permission for a number of specified principal IDs that are also the principal IDs of friends. The server confirms that the principal IDs are those of friends. |
The user that uploaded the data has owner privileges. Users with owner privileges can access and update the data in addition to performing other operations available only to the data owner.
Users that do not have privileges can also manipulate the target data by specifying a password. A password can be obtained with the DataStoreClient::GetPasswordInfo
function. An access password and update password is set for all data when it is uploaded. Users that then receive those passwords from the data owner can enter them to enable use of all of the same operations that are available to users that actually have the corresponding privileges. No error occurs if a user with privileges enters an incorrect password, and that user still has permission to access and update the data. There is no password that grants owner privileges when entered. Also, passwords cannot be specified with some functions. Depending on the status of the data, referencing and updating cannot be performed even if there is permission. For more information, see Data Status.
For more information about the privileges required for each operation, see Table 6.3 Required Privileges.
Function Name | Required Privileges |
---|---|
DataStoreClient:: GetObject |
Reference |
DataStoreClient:: PostObject |
N/A |
DataStoreClient:: UpdateObject |
Update |
DataStoreClient:: DeleteObject |
Update |
DataStoreClient:: ChangeMeta |
Update |
DataStoreClient:: GetMeta |
Reference |
DataStoreClient:: SearchObject |
Reference |
DataStoreClient:: GetRating |
Reference |
DataStoreClient:: RateObject |
Reference |
DataStoreClient:: ResetRating |
Update |
DataStoreClient:: TouchObject |
Reference |
DataStoreClient:: GetPersistenceInfo |
Reference |
DataStoreClient:: PerpetuateObject |
Owner |
DataStoreClient:: UnperpetuateObject |
Owner |
DataStoreClient:: GetPasswordInfo |
Owner |
DataStoreClient:: CompleteSuspendedPostObject |
Owner |
Note
To download data that has been uploaded using SpotPass, when you upload data you must specify access permissions to DataStoreConstants::PERMISSION_FRIEND
, DataStoreConstants::PERMISSION_SPECIFIED
, or DataStoreConstants::PERMISSION_SPECIFIED_FRIEND
while also specifying the data access flag (see Section 6.4.6) to DataStoreConstants::DATA_FLAG_USE_NOTIFICATION_ON_POST
.
For more information about linking to SpotPass, see Section 6.14.
You can specify up to NUM_TAG_SLOT
tags as meta-information of the data to upload. Each tag can have up to MAX_TAG_LENGTH
of either printable ASCII characters or multibyte characters. Specify multibyte characters with the _T()
macro. Do not end a tag string with an ASCII space (0x20). If you do so, the system ignores the trailing space when setting and searching on the tag. You cannot set the same tag more than once for a particular data object.
Code 6.2 Setting Tags
DataStorePostParam postParam;
// Set the tags. You cannot set the same tag more than once per data object.
qVector<String> tags;
tags.push_back("ABC");
tags.push_back(_T("DEF"));
tags.push_back(_T("GHI"));
postParam.SetTags(tags);
Data stores make it possible to rate uploaded data. To use this feature, the first time you upload the data, you must set and initialize a DataStoreRatingInitParam
object with the DataStorePostParam::SetRatingSetting
function. The values that can be set are shown in Table 6.4 DataStoreRatingInitParam
Parameters. To use the rating feature on initialized data, use the data rating functions. (For more information, see section 6.10 Rating Data.)
Name | Description | Initial Value | Settings Function |
---|---|---|---|
Initial value for the ratings total value | Sets the initial value for the ratings total value. | 0 | SetInitialValue |
Minimum rating value | Sets the minimum value for the ratings values that can be rated at the same time. | Not set | SetRangeMin |
Maximum rating value | Sets the maximum value for the ratings values that can be rated at the same time. | Not set | SetRangeMax |
Duplicate lock | Sets the duplicate lock when rating. You can specify several restrictions, such as making users wait for an hour before making another rating, or only allowing one rating per day. | Not set | SetLock |
Option flag | Specify options for ratings. See Table 6.5. | Not set | SetFlag |
Privilege | Description |
---|---|
DataStoreConstants:: RATING_ FLAG_ MODIFIABLE |
Ratings are editable. If the same user makes another rating, the new rating value replaces the first rating value. If this flag is not set, then each rating is added as a separate rating. |
DataStoreConstants:: RATING_ FLAG_ ROUND_ MINUS |
Negative ratings total values are rounded to zero. |
DataStoreConstants:: RATING_ FLAG_ DISABLE_ SELF_ RATING |
Prevent users from rating themselves. |
Note
About duplicate locks (Code 6.4).
Set the locking method by specifying a DataStoreRatingLockInitParam
object with the DataStoreRatingInitParam::SetLock
function.
DataStoreRatingLockInitParam::SetIntervalLock
function.Specifies a lock in seconds. Specify the number of seconds with intervalSec
. This setting prevents another rating for the specified number of seconds (such as 900) from the last one.
DataStoreRatingLockInitParam::SetPeriodicLock
function.Locks ratings for the specified period. Specify a period for period
(for example, every Monday through every Sunday, until the first of the next month, and so on), and specify a time from -23 to 23 (UTC) for hour
. For example, you can specify to reset rating locks every Monday at 0:00 Japan Standard Time.
DataStoreRatingLockInitParam::SetDaysAfterLock
function.Locks ratings for the specified number of days. Specify a number of days for days
, and specify a time from -23 to 23 (UTC) for hour
. For example, you can allow ratings to be made once per day.
DataStoreRatingLockInitParam::SetPermanentLock
function.Sets a permanent lock. This setting sets a permanent lock, so that after a rating is made it cannot be rated again.
Code 6.3 Initializing Ratings
DataStorePostParam postParam;
DataStoreRatingInitParam ratingInitParam;
// Initialize the rating (use three slots).
qMap<qInt8, DataStoreRatingInitParam> ratings;
for (qInt8 i = 0; i < 3; ++i) {
ratings.insert(std::make_pair(i, ratingInitParam));
}
postParam.SetRatingSetting(ratings);
Code 6.4 Sample Specification of Duplicate Locks
// Lock for the specified number of seconds. Lock for 900 seconds.
DataStoreRatingInitParam ratingInitParam;
DataStoreRatingLockInitParam ratingLockInitParam;
ratingLockInitParam.SetIntervalLock(900);
ratingInitParam.SetLock(ratingLockInitParam);
// Lock for the specified number of days. You can make one rating per day. Rating locks are reset at 0:00 JST (15:00 UTC).
DataStoreRatingInitParam ratingInitParam;
DataStoreRatingLockInitParam ratingLockInitParam;
ratingLockInitParam.SetDaysAfterLock(0, 15);
ratingInitParam.SetLock(ratingLockInitParam);
// Lock for the specified period. Reset locks every Monday at 0:00 UTC.
DataStoreRatingInitParam ratingInitParam;
DataStoreRatingLockInitParam ratingLockInitParam;
ratingLockInitParam.SetPeriodicLock(DataStoreConstants::RATING_LOCK_PERIOD_MON, 0);
ratingInitParam.SetLock(ratingLockInitParam);
// Lock for the specified period. Reset locks at the end of each month JST.
DataStoreRatingInitParam ratingInitParam;
DataStoreRatingLockInitParam ratingLockInitParam;
ratingLockInitParam.SetPeriodicLock(DataStoreConstants::RATING_LOCK_PERIOD_DAY1, -9);
ratingInitParam.SetLock(ratingLockInitParam);
You can store up to 1,024 bytes of binary data in the meta-information. Storing and retrieving meta-binaries only accesses the game server, so it is faster than using the storage server. For this reason, you can allocate usage based on the data size and purpose, such as using meta-binaries for small amounts of data, and a storage server for larger data.
Code 6.5 Setting Meta-Binary Data
static const META_BINARY_SIZE = 3;
DataStorePostParam postParam;
// Set the binary data.
qByte metaBinary[META_BINARY_SIZE];
memcpy(metaBinary, "123", META_BINARY_SIZE);
postParam.SetMetaBinary(metaBinary, META_BINARY_SIZE);
The settings for the data that is uploaded are configured by the DataStorePostParam::SetDataFlag
function. Table 6.6 Settings Flags describes the meanings of the different flags. Do not specify flags that are not shown in the table.
Flag | Description |
---|---|
DataStoreConstants:: DATA_ FLAG_ NONE |
None of the settings flags are used. |
DataStoreConstants:: DATA_ FLAG_ NEED_ REVIEW |
When uploading completes, the status of the data is DataStoreConstants:: DATA_ STATUS_ PENDING and cannot be seen by anybody except the owner. To make data viewable, the operator must use NMAS to change the status of the data, as explained in Section 6.19. |
DataStoreConstants:: DATA_ FLAG_ PERIOD_ FROM_ LAST_ REFERRED |
The expiration of the data is extended when it is referenced or updated by functions such as GetObject , UpdateObject , and ChangeMeta . For more information, see Section 6.17.2. |
DataStoreConstants:: DATA_ FLAG_ USE_ NOTIFICATION_ ON_ POST |
Makes uploaded data downloadable from the BOSS server.( (For more information, see Section 6.14.) |
DataStoreConstants:: DATA_ FLAG_ NEED_ COMPLETION |
After the DataStoreClient::PostObject function completes, disable the data on the server until the DataStoreClient::CompleteSuspendedPostObject function is executed. For more information, see Section 6.4.7. |
You can use the batch-upload feature to upload multiple related data sets. Use this feature to guarantee the atomicity of data store operations; that is, either all of the data is uploaded or none of the data is uploaded. Use this feature to prevent data from being partially uploaded, such as when the console is accidentally turned off or disconnected from the network.
To use this feature, first set the DataStoreConstants::DATA_FLAG_NEED_COMPLETION
flag, and then upload an arbitrary number of data sets with the DataStoreClient::PostObject
function. When the upload completes, the data is registered on the server in a status that cannot be accessed by anyone including the owner. After all of the data is uploaded, enable all of the data on the server at the same time by passing the corresponding data IDs as arguments to the DataStoreClient::CompleteSuspendedPostObject
function. The data can then be accessed or updated just like normal data.
If any of the data that corresponds to the data IDs given to the DataStoreClient::CompleteSuspendedPostObject
function is invalid for any reason, or the process fails, the process is rolled back. If an error occurs, you can use the CallContext::GetOutcome
function to get the first error. If persistence settings were configured for the data, they take effect when this asynchronous process is successful. Uploaded data must be enabled with this function within three hours from when the DataStoreClient::PostObject
function was started. After three hours, the data on the server is automatically deleted. When DataStoreConstants::DATA_FLAG_NEED_COMPLETION
was not specified, this function does not need to be called because the data on the server becomes valid at the same time the DataStoreClient::PostObject
function completes. You do not need to use this feature when you upload only a single data set. Atomicity of data store operations is guaranteed for a single set of data even when DataStoreConstants::DATA_FLAG_NEED_COMPLETION
is not specified, and it is not possible for that data to be only partially uploaded to the server.
When data is uploaded, a data ID is usually assigned automatically. If you want to upload data to a predetermined data ID, there is a feature that lets you specify the data ID when uploading. When this feature is used, you can implement a series of actions where the upload and rating slot are initialized if the specified data ID does not contain any data, and then the usual rating process takes place.
For ratings, you can perform the entire series of actions described above with DataStoreClient::RateObjectWithPosting
or DataStoreClient::RateObjectWithPostings
. If there is no data at the specified data ID, these functions both initialize and perform the rating; if there is data at the specified data ID, they perform the rating as usual.
This feature has the following limitations.
900000
and 999999
. In consideration of load, please limit the total number of data items to upload to around 10,000. Normally, uploaded data items are indexed starting at 1,000,000, so IDs exceeding the range cannot be specified. DataStoreConstants::PERMISSION_PUBLIC
.DataStoreClient::DeleteObject
function. Use NMAS if the data needs to be deleted.DataStoreClient::ChangeMeta
function. (Support to be added at a later date.)Note
The default value of access and update permissions for DataStorePostParam
is DataStoreConstants::PERMISSION_PRIVATE
. Use the DataStorePostParam::SetAccessPermission
and DataStorePostParam::SetUpdatePermission
functions to set DataStoreConstants::PERMISSION_PUBLIC
explicitly.
Only some parameters can be set using DataStorePostParam
. In Table 6.1, these parameters are the name, data type, initial rating slot setting, and meta binary.
DataStorePostParam::SetName
DataStorePostParam::SetDataType
DataStorePostParam::SetRatingSetting
DataStorePostParam::SetMetaBinary
If you call a member function other than those listed above and set something other than the default value, QERROR(DataStore, InvalidArgument)
will be returned when you call DataStoreClient::PostObject
.
You can specify multiple data IDs and upload multiple data items. Up to BATCH_PROCESSING_CAPACITY_POST_OBJECT
IDs can be specified.
The following errors are returned by CallContext::GetOutcome
. - QERROR(DataStore, OperationNotAllowed)
: The specified data ID already contain data. - QERROR(DataStore, InvalidArgument)
: The parameter is invalid.
Use the DataStoreClient::GetObject
function to download uploaded data. The following methods for downloading data are available.
Specify the pointer to the buffer where the data to download is to be saved in the buffer parameter, and specify the buffer size in the bufferSize parameter. The buffer size must be larger than the size of the data to download.
Specify a class object that inherits DataStoreGetObjectEventListener
and that overrides the DataStoreGetObjectEventListener::ProcessResponse
function in the eventListener parameter. Use if you want to download your data in chunks when you cannot allocate enough memory at one time.
Warning
When using an event listener, if the DataStoreGetObjectEventListener::ProcessResponse
function of the class being overridden returns false
for a set period of time, the connection with the storage server is broken, causing the data download to fail. Avoid an implementation where the returned value is false
for longer than 10 seconds. In addition, this function is intended for flow control. Do not use it to pause or stop downloads.
If the process succeeds, specify DataStoreConstants::DATA_FLAG_PERIOD_FROM_LAST_REFERRED
when uploading data to update the expiration. For more information, see Section 6.17.2.
Warning
You cannot use the DataStoreClient::GetObject
function unless you are using a storage server. Use the DataStoreClient::GetMeta
function to get the metadata when you want to get your data. For more information, see Section 6.12 Getting Metadata.
Warning
NEX 3.5 and later versions were changed to no longer update the reference date and reference count. For more information, see Section 6.11.
Use the DataStoreClient::UpdateObject
function to update uploaded data. The following methods for updating data are available. Use an event listener if you want to upload your data in chunks because you cannot allocate enough memory at one time.
Specify the following arguments: a pointer to a ProtocolCallContext
object, a DataStoreUpdateParam
object, a pointer to a buffer of the data to upload, and whether to copy the content of the buffer inside the library.
Specify the following arguments: a pointer to a ProtocolCallContext
object, a DataStoreUpdateParam
object, and a pointer to a DataStorePostObjectEventListener
object.
If the action is successful, the date modified and the expiration date (metadata in the updated data) are updated. For more information, see Section 6.17.2.
Warning
You cannot use the DataStoreClient::UpdateObject
function unless you are using a storage server. Use the DataStoreClient::ChangeMeta
function to update metadata when you want to update your data. For more information, see Section 6.13 Updating Metadata.
Use the DataStoreClient::DeleteObject
function to delete uploaded data. Note that deleted date cannot be recovered To specify a persistence slot ID and delete data, use the DataStoreClient::UnperpetuateObject
function. When persistent data is deleted, it is automatically made non-persistent.
You can delete uploaded data as a batch process. Use the DataStoreClient::DeleteObject
function in the same way as when you make individual deletions.
Use the DataStoreClient::SearchObject
function to search for uploaded data. The search results are received as an DataStoreSearchResult
object. The data that can be obtained is listed in Table 6.7. When searching for data, a maximum of 100 hits can be obtained at one time.
The items shown in Table 6.8 can be set as search conditions in DataStoreSearchParam
.
DataStoreSearchParam::SetSearchType
function is shown in Figure 6.1.DataStoreSearchParam::SetResultOption
function to include tags, ratings information, and meta-binaries.Warning
When getting search results including meta-binary data, your implementation must adjust the number of results retrieved so that the total size of the search results is not too large. If the overall size is large, it may take longer to retrieve the data due to lower packet transfer efficiency. As a rule, keep the total size of meta-binary data in meta-information to no more than 20 KB. For example, if the size of the meta-binary data is 1 KB, adjust the number retrieved at once to 20.
Name | Get Function |
---|---|
Total number of search hits | GetTotalCount |
Search results | GetResult |
Whether the number of search matches is accurate | GetTotalCountType |
Note
To prioritize the response speed of searches, when the number of matches (DataStoreSearchResult::GetTotalCountType
) exceeds a particular amount, the DataStoreSearchResult::GetTotalCount
function may not return an accurate count. Account for the following in your implementation.
DataStoreSearchResult::GetTotalCountType
is DataStoreConstants::SEARCH_RESULT_TOTAL_EXACT
, the count is accurate. However, there are small errors with frequent search conditions, because the system caches searches for a set period.DataStoreSearchResult::GetTotalCountType
is DataStoreConstants::SEARCH_RESULT_TOTAL_MINIMUM
, it indicates that there is more matching data than the value that DataStoreSearchResult::GetTotalCount
returned.Name | Description | Initial Value | Settings Function |
---|---|---|---|
Search type | Set what data to search for in accordance with access privileges.( Figure 6.1) | DataStoreConstants:: SEARCH_ TYPE_ PUBLIC |
SetSearchType |
PrincipalID to search for | Narrows the search by the principal IDs of the owners of the uploaded data. | Empty | SetOwnerIds |
Principal ID type of the owner of uploaded data | The type of the principal ID of the person who uploaded the data. | DataStoreConstants:: SEARCH_ TARGET_ ANYBODY |
SetOwnerType |
PrincipalID of the access privileges holder |
Specify this parameter when the search type is SEARCH_ TYPE_ PUBLIC or SEARCH_ TYPE_ FRIEND . It can be used to choose access rights for the send destination and search for data that a specific person has received. |
Empty | SetDestinationIds |
Data type | The type of data to search for. | DataStoreConstants:: INVALID_ DATA_ TYPE |
SetDataType |
Start time of data upload | Data with the specified date or later. | DataStoreConstants:: INVALID_ DATE_ TIME ) |
SetCreatedAfter |
Date uploaded end | Data with the specified date or sooner. | DataStoreConstants:: INVALID_ DATE_ TIME ) |
SetCreatedBefore |
Column to sort on | The column on which to sort the search results. | DataStoreConstants:: SEARCH_ SORT_ COLUMN_ DATAID |
SetSearchSortOrderColumn |
Sort order | Whether to sort the search results in ascending or descending order. | DataStoreConstants:: SEARCH_ SORT_ ORDER_ ASC |
SetSearchSortOrder |
Return value option | Specify this parameter to include tags, rating values, or binary data in the search results. | 0 | SetResultOption |
Tags | Tags to search for. Items matching all specified tags are retrieved. | Empty | SetTags |
Search range | The range in which to search. | ResultRange |
SetResultRange |
Whether the search result cache is used. | Sets whether to use the search results cache. When the cache in enabled, search results are retrieved from a cache maintained on the server. | false | SetUseCache |
Figure 6.1 Data Searched by Search Type
Note
For example, when access privileges for the search data is set to DataStoreConstants::PERMISSION_PUBLIC
, if the search type is set to DataStoreConstants::SEARCH_TYPE_PUBLIC
, the data is the search target data for anyone who searches and the data can be in the search hits. If the access privileges are DataStoreConstants::PERMISSION_FRIEND
, you can set the search type to DataStoreConstants::SEARCH_TYPE_FRIEND
to enable data to be searched and hits returned when it is a friend doing the searching. Normally, only data with a status of NONE
can be searched, but data with status of PENDING
or REJECTED
where the local user is the owner can be searched if DataStoreConstants::SEARCH_TYPE_OWN_PENDING
, DataStoreConstants::SEARCH_TYPE_OWN_REJECTED
, or DataStoreConstants::SEARCH_TYPE_OWN_ALL
is used.
Use the DataStoreSearchParam::SetUseCache
function to enable the search result cache. When the search result cache is enabled, search results are temporarily cached on the server and then retrieved from the cache if a search with the same criteria is performed at a later time. By default, search results are cached for three minutes. Using the search result cache can improve the speed of search responses in most cases.
Because search results are retrieved from the cache, however, if the target search data was updated or new data was uploaded since the last search, the updated or new data may not be reflected in your search results depending on when the subsequent search is performed.
We recommend using the search results cache if it is not critical that search results always be up to date or if several users will be searching using the same search conditions in your application. In such cases, limit the number of cached searches to 200.
Searching by tags or sorting search results by a column other than data ID can result in spikes in game server load, which in turn can make search responses sluggish and increase the rate of failure when users attempt to log in to the game server. Nintendo also recommends caching search results if users are likely to perform these types of computationally expensive searches.
Depending on the application, displaying data IDs as is may make it easy for malicious users to determine the scope of services or level of security in the application. Letting users search using raw data IDs may enable them to specify unexpected values to gain invalid access to data that they are not supposed to have access to.
Converting data IDs using the DataStoreDataCode
class allows you to obtain datacode strings unique to each title which are both suitable for display in the application and cannot be easily predicted.
Datacode strings can be a maximum of 14 characters in length including the data ID (up to 56 bits) and checksum (8 bits), and can contain any of the following 28 characters: 0 1 2 3 4 5 6 7 8 9 B C D F G H J K L M N P R T V W X Y. The length of datacode strings varies depending on the data ID values. For example, data IDs from 0 to 268,435,455 can be represented with 1 to 8 characters, and data IDs from 0 to 4,294,967,295 can be represented with 1 to 9 characters.
To get a datacode string, use the DataStoreDataCode::CreateFromDataId
function to create a DataStoreDataCode
object, and then use the DataStoreDataCode::ToDataCodeString
function. Use the DataStoreDataCode::ToDataCodeStringZeroPad
function to left-pad data codes with zeroes to ensure that datacode strings are always 14 characters long.
Use the DataStoreDataCode::CreateFromDataCodeString
function to convert datacode strings back to DataStoreDataCode
objects. Use the DataStoreDataCode::IsValid
function to determine whether a datacode string is valid. Use the DataStoreDataCode::GetDataId
function to get the data ID corresponding to a datacode string. In the DataStoreDataCode::CreateFromDataCodeString
function, lowercase characters are converted to uppercase characters, and characters that are suspected to be typos are converted to the appropriate characters. (I->1, Q->0, O->0, Z->2, S->5)
Specify the access key for your title as the checksum key when using the DataStoreDataCode::CreateFromDataId
and DataStoreDataCode::CreateFromDataCodeString
functions. These functions still work if you specify a value other than the access key for your title, but you will lose the ability to calculate and test datacode strings on non-client systems.
With data store, 16 fields (called slots) are provided for each data ID that is uploaded, and ranking total value and information about the number of times ranked are saved and can be accessed. This feature is designed to allow public ratings of content, such as a five point scale or a “like” system, and to allow those ratings to be accessed.
You must initialize the ratings of data when you upload it to use these features. (For more information, see Section 6.4.4. The following features are available for data that has been initialized.
Warning
Your ratings implementation must ensure that total ratings values fit into a 64-bit signed int
. If the total exceeds this range, it is rounded to the maximum or minimum value.
Use the DataStoreClient::RateObject
function to calculate ratings total values. When initializing ratings, only the provided slot can be rated.
Use the DataStoreClient::GetRating
function to get the ratings information or ratings log. When initializing ratings, ratings information can be obtained only from the provided slot. Ratings information can be obtained with the DataStoreRatingInfo
object and the ratings log with the DataStoreRatingLog
object, and the information obtained from them is shown in Table 6.9 and Table 6.10, respectively.
Use the DataStoreClient::ResetRating
function to reset ratings information and the ratings log. The ratings total value is restored to the default value, and the number of times rated becomes 0. The ratings log is cleared.
Use the DataStoreClient::RateObject
function in the same way as when you rate individual objects.
Use the DataStoreClient::GetRating
function in the same way as when you get individual ratings. There is no function to get ratings as a batch process along with the ratings log.
As with resetting a single rating, use the DataStoreClient::ResetRating
function to reset multiple ratings.
Name | Get Function |
---|---|
The total value of the rating | GetTotalValue |
Number of times rated | GetCount |
Initial value for the ratings total value | GetInitialValue |
Name | Get Function |
---|---|
Whether oneself rated in the past | IsRated |
Rating value when oneself rated previously | GetRatingValue |
Date and time the duplicate lock was released | GetLockExpirationTime |
This action is no longer possible in NEX 3.5 because the reference date and count will be removed. These values are no longer updated when calling the DataStoreClient::GetObject
and DataStoreClient::TouchObject
functions. These functions update the expiration if DataStoreConstants::DATA_FLAG_PERIOD_FROM_LAST_REFERRED
is specified when uploading data. This cannot be specified in the DataStoreClient::SearchObject
or DataStoreClient::ChangeMeta
functions.
The DataStoreClient::TouchObject
function provides functionality equivalent to specifications that call for the expiration to be updated when data is downloaded (Section 6.5). These functions are expected to be used when using an upload of only meta-binaries without using the storage server, or when accessing other metadata such as ratings information. For more information about changing the timestamp value, see Section 6.17.2.
Use the DataStoreClient::GetMeta
function to get the metadata of uploaded data.
If the metadata you want to get is a tag, rating information, meta-binary, or principal ID with privileges, specify the flag for the data you want to get with the DataStoreGetMetaParam::SetResultOption
function. If the operation succeeds, the function stores the value of the metadata in the DataStoreMetaInfo
object. Table 6.11 Information That Can Be Obtained with DataStoreMetaInfo
shows the information that can be obtained from a DataStoreMetaInfo
object.
Name | Get Function |
---|---|
Data ID | GetDataId |
Principal ID | GetOwnerId |
Data size | GetSize |
Status | GetStatus |
Name | GetName |
Data type | GetDataType |
Access privileges | GetAccessPermission |
Update permissions | GetUpdatePermission |
Creation date and time | GetCreatedTime |
Date modified | GetUpdatedTime |
The number of valid days | GetPeriod |
Reference count (Do not use.) | GetReferredCount |
Configuration flag | GetDataFlag |
The date and time accessed | GetReferredTime |
Period of validity | GetExpireTime |
Tags | GetTags |
Rating information | GetRating |
Meta-binary data | GetMetaBinary |
You can get metadata from uploaded data as a batch process. Use the DataStoreClient::GetMeta
function in the same way as when you get individual metadata items.
Warning
When getting the data including meta-binary as a batch process, your implementation must adjust the amount of data to obtain so that the total size of the batch results is not too large. If the overall size is large, it may take longer to retrieve the data due to lower packet transfer efficiency. As a rule, keep the total size of meta-binary data in meta-information to no more than 20 KB. For example, if the size of the meta-binary data is 1 KB, adjust the number retrieved at once to 20.
Use the DataStoreClient::ChangeMeta
function to update the metadata of uploaded data. Specify the flag for the metadata you want to update with the DataStoreChangeMetaParam::SetModificationFlag
function. Table 6.12 Metadata Update Flags provides a list of the available flags for updating metadata.
If the action completes normally and DataStoreConstants::MODIFICATION_FLAG_PERIOD
and DataStoreConstants::MODIFICATION_FLAG_UPDATED_TIME
have been set to flags, the update time and period of validity (expiration date) are updated as shown in Section 6.17.2.
Flags | Description |
---|---|
DataStoreConstants:: MODIFICATION_ FLAG_ NONE |
Not set. |
DataStoreConstants:: MODIFICATION_ FLAG_ NAME |
Change title. |
DataStoreConstants:: MODIFICATION_ FLAG_ ACCESS_ PERMISSION |
Change access permission. |
DataStoreConstants:: MODIFICATION_ FLAG_ UPDATE_ PERMISSION |
Change update permissions. |
DataStoreConstants:: MODIFICATION_ FLAG_ PERIOD |
Change the number of valid days. |
DataStoreConstants:: MODIFICATION_ FLAG_ METABINARY |
Change meta-binary data. |
DataStoreConstants:: MODIFICATION_ FLAG_ TAGS |
Change tags. |
DataStoreConstants:: MODIFICATION_ FLAG_ UPDATED_ TIME |
Update the updated time to the current time. |
DataStoreConstants:: |
Changes the data type. |
DataStoreConstants:: |
Changes the reference count. (Do not use.) |
DataStoreConstants:: |
Changes the status. |
You can update meta-information from uploaded data as a batch process. Use the DataStoreClient::ChangeMeta
function in the same way as when you change individual metadata items.
To update metadata by comparing and swapping, set DataStoreChangeMetaCompareParam
using the DataStoreChangeMetaParam::SetChangeMetaCompareParam
function. Flags and values for information being compared are set in DataStoreChangeMetaCompareParam
.
If the set value and the actual value are not the same, no change is made and the CallContext::GetOutcome
function returns QERROR(DataStore, ValueNotEqual)
.
Flags | Description |
---|---|
DataStoreConstants:: |
Not set. |
DataStoreConstants:: |
Compare titles. |
DataStoreConstants:: |
Compare access permission. |
DataStoreConstants:: |
Compare update permission. |
DataStoreConstants:: |
Compare the number of days in the valid period. |
DataStoreConstants:: |
Compare binary data. |
DataStoreConstants:: |
Compare tags. |
DataStoreConstants:: |
Compare the data type. |
DataStoreConstants:: |
Compare the reference count. (Do not use.) |
DataStoreConstants:: |
Compare status. |
DataStoreConstants:: |
Compare all. |
You can use SpotPass (BOSS) to upload or download data even when the application is not running, by accessing the DataStore
server in the background.
This feature uses BOSS as included in CTR_SDK. For more information about how to register tasks or use BOSS storage, see section 4.2 SpotPass in CTR Programming Manual: Wireless Communication. You must apply on OMAS before using this feature. You do not need to initialize NEX or connect to the game server before using the BOSS API.
Warning
DataStore
upload and download tasks have no mechanism for notifying the user when the service terminates. If you need to notify the user when the service terminates, use a method such as the following to detect when the service terminates.
NgsFacade::Login
and NgsFacade::GetLastLoginErrorCode
functions to detect the error code for the termination of the service.When using this function on the CTR, keep the data ID so that it does not exceed a range of 32 bits.
You can perform a DataStore
upload using SpotPass by registering the nn::boss::DataStoreUploadAction
class to the task. Each DataStore
upload task can upload one data item. To upload multiple items or alter what data is sent depending on the recipient, you must prepare one task for each item. Parameters for data that can be uploaded to the DataStore
using SpotPass are as indicated in Table 6.14.
Name | Values That Can Be Configured | Settings Function |
---|---|---|
Game Server ID | Issued by OMAS. | nn:: |
Access key. | Issued by OMAS. | nn:: |
Parameters for data that can be uploaded using SpotPass are as indicated in Table 6.15. Any data for which the setting function is set to "none" is given a fixed value. DataStoreConstants::DATA_FLAG_USE_NOTIFICATION_ON_POST
is specified for the settings flag. This option sends a notification to those who are indicated to have access privileges. People who receive this notification can receive the data using a BOSS download. (For more information, see Section 6.14.2.)
Warning
Notifications are sent as soon as the data is done being uploaded to the storage server. No notifications are sent if only the meta-binary data is uploaded and the storage server is not used.
Name | Values That Can Be Configured | Settings Function |
---|---|---|
Size | The size of the file indicated by the file handle specified by nn::boss::DataStoreUploadAction::Initialize is set automatically. |
It is set automatically. |
Name | Empty string. | None. |
Data type | Arbitrary value. | nn:: |
Access privileges | nn::
nn::
nn::
When specifying nn::
|
nn:: |
Update permissions | DataStorePermission( DataStoreConstants:: |
None. |
Configuration flag | DataStoreConstants:: |
None. |
The number of valid days | 1–365 | nn:: |
Tags | Empty | None. |
Data for initialization of rating slots | Empty | None. |
Meta-binary data | Empty | None. |
Persistence setting | DataStorePersistenceInitParam | None. |
Warning
Do not perform any further action for tasks that have successfully uploaded. In short, even if the execution count is two or more, the data is not uploaded multiple times. If an upload error occurs after increasing the execution count, upload is retried that same number of times. There is no method for accurately determining from the application whether the DataStore
upload task uploaded data to the server.
If the access permissions are set to either nn::boss::DstKind_FRIEND
or nn::boss::DstKind_SPECIFIED_FRIEND
, the system checks whether the other party has a friend relationship when data is either uploaded or downloaded. If this functionality causes a problem, use nn::boss::DstKind_SPECIFIED
in your implementation to check whether the data owner is a friend when downloading.
Data that was uploaded using SpotPass can be downloaded by any user with access privileges, if the upload settings specified notification. This situation specifically applies to data uploaded using the parameters set as indicated in the comments in Section 6.4.2, or to data uploaded using SpotPass. (For more information, see Section 6.14.1.) You can perform a DataStore
upload using SpotPass by registering the nn::boss::DataStoreUploadAction
class to the BOSS task. For more information about registering tasks, see section 4.2 SpotPass in CTR Programming Manual: Wireless Communication. No more than one DataStore
download task can be registered on the same game server. One task receives all of the data for which you are notified.
The following Table 6.16 describes the game server setting parameters for uploading to the DataStore
SpotPass.
Name | Values That Can Be Configured | Settings Function |
---|---|---|
Game Server ID | Issued by OMAS. | nn:: |
Access key. | Issued by OMAS. | nn:: |
You can send a notification to notify a user of new data when data has been downloaded. Activate notification issuing or perform settings by calling the nn::boss::DataStoreDownloadAction::SetNewsPublication
function. Make sure to set the first argument (the serial ID for notifications) in the parameters specified with nn::boss::DataStoreDownloadAction::SetNewsPublication
to the ID issued by Nintendo. The content of the notification is a set text. This text cannot be changed by the sender or based on the content of the received data.
The following Table 6.17 describes the location where the metadata attached to the downloaded data is stored.
Metadata Name | Parameter Name for Stored NS Data |
---|---|
Data ID | Serial ID. |
Data type | Private data type. |
Registering a DataStore
download task queries the server to see whether a notification has been sent to you, at the set execution interval. After sending of the data has been confirmed, it is downloaded and written to BOSS storage. Data is downloaded in the order of when the relevant notifications were received. If BOSS storage is full, old data is automatically deleted.
Warning
How much data was downloaded is recorded in the task. Although data is not downloaded more than once as long as a task exists, if a task is registered again after it is deleted, the data that was previously received may be downloaded again. In this case, at most 20 items are downloaded again. To hide duplicated data from the user, take measures such as having the application remember the serial ID of the 20 most recently received items.
Normal uploaded data is deleted automatically after its period of validity has expired. Use the data-persistence feature to configure the data so it is perpetuated and not automatically deleted. Each user can perpetuate up to 16 sets of data. Perpetuated data can be referenced by using a principal ID and a slot ID that stores its persistence information (persistence slot IDs 0 through 15). This feature has the following uses.
To perpetuate data that has been uploaded already, use the DataStoreClient::PerpetuateObject
function. The period of validity for the perpetuated data becomes DataStoreConstants::PERMANENT_DATE_TIME
. If that same persistence slot ID was previously in use, its data is unperpetuated. The same data ID cannot be set to multiple persistent slot IDs.
To make data persistent at the same time that it is uploaded, configure persistence for the DataStorePostParam
class object you specify when you call the DataStoreClient::PostObject
function. Specifically, use the DataStorePostParam::SetPersistenceInitParam
function to set a persistence slot ID for the specified DataStorePersistenceInitParam
class object. If the same persistence slot ID was used in the past, its data is unperpetuated. To delete the data at the same time that it is unperpetuated, specify true
for the DataStorePersistenceInitParam::SetDeleteLastObject
function. To maintain consistency in this series of processes, the data ID set to the persistence slot is always a valid value around the DataStoreClient::PostObject
function call. In other words, when you reference data using the DataStoreClient::GetObject
and DataStoreClient::GetMeta
functions, you can always get valid data if you specify the target data using a persistence slot ID with DataStorePersistenceTarget
instead of using a data ID. This property is unrelated to the settings configured with the DataStorePersistenceInitParam::SetDeleteLastObject
function.
To restore perpetuated data to its original state, use the DataStoreClient::UnperpetuateObject
function. When you unperpetuate the data, it is reconstituted as data that can be automatically deleted. The unperpetuated data expires after the current time plus the number of valid days. When you delete data with the DataStoreClient::DeleteObject
function, the data is automatically removed from its persistence slot and unperpetuated. When the option to delete past data with the DataStoreClient::UnperpetuateObject
function is enabled, it works like the DataStoreClient::DeleteObject
function works to delete data.
To get data ID from the principal ID and persistence slot ID, use the DataStoreClient::GetPersistenceInfo
function. There is an API to get one set of information by specifying a single persistence slot ID, and an API to get information as a batch process by specifying multiple persistence slot IDs.
An access password and update password is set for all data when it is uploaded. Giving these passwords to users grants them access and update rights for the data if they did not already have them previously. For more information about passwords, see Section 6.4.2. Use the DataStoreClient::GetPasswordInfo
function to get passwords.
Each piece of data that is uploaded has a status, and operations change according to the status. The status can be obtained with the DataStoreClient::GetMeta
function.
Data Status | Description |
---|---|
NONE |
Normal state. Data for which upload completes automatically transitions to this status. Access and modification are possible according to the set privileges and passwords. |
CREATING |
Data is being uploaded. No one, including the owner, can access or modify. |
PENDING |
The data is being tested. Uploaded data for which the DataStoreCnstants:: DATA_ FLAG_ NEED_ REVIEW flag is set transitions to this status instead of NONE . Access is not allowed with set privileges and passwords, and only the owner can access and modify. |
DELETING |
Data for which a delete request has been received. No one, including the owner, can access or modify. Deleting data with the DataStoreClient:: DeleteObject function or NMAS transitions to this status. After that, automatically transition to DELETED after expiration. |
DELETED |
Data for which the deletion procession has been executed on the storage server. No one, including the owner, can access or modify. Expired data transitions to this status. Thereafter, the record is automatically deleted. |
REJECTED |
Data that was rejected during testing. The system does not automatically transition data to this status. As with PENDING , access is not allowed with set privileges and passwords, and only the owner can access and modify. |
A client cannot access the data with the status of CREATING
, DELETING
, or DELETED
, and can only check whether the data exists from NMAS. By manipulating data from NMAS, the status can transition between NONE
, PENDING
, DELETING
, and REJECTED
. Transition to NONE
, PENDING
, or REJECTED
is possible by editing data. Transition to DELETING
is possible by deleting data.
Data that has been transitioned to DELETING
even once cannot receive using SpotPass.
Figure 6.2 Changing Timestamp Values When Using the API shows how timestamp values are changed when using the different data store functions.
Figure 6.2 Changing Timestamp Values When Using the API
Multiple APIs have overloaded member functions that can process multiple data sets as a batch process at the same time. You can batch-process up to 100 items at a time. If you need to process more than 100 items, break them up into groups of 100 or less, and call the function multiple times.
If an asynchronous process fails, the result for each data set is not stored in the qVector<qResult>
object. After confirming that asynchronous processing was successful with the CallContext::GetState
function, check the content of qVector<qResult>
as needed. For functions that have a flag that determines whether to continue only when all asynchronous processes were successful, you can get the first error that occurs during the process with the CallContext::GetOutcome
function by setting this flag to true
. In this case, the data on the server is not affected. Use the QSUCCEEDED
macro or cast to qBool
to determine whether the result stored in qResult
indicates that the process was successful.
HTTP processes are not guaranteed to be completed when they are canceled using the ProtocolCallContext::Cancel
function or when the DataStoreClient
object is destroyed. HTTP processes are guaranteed to be completed when the NgsFacade
object is destroyed. To prevent problems, make sure that the NgsFacade
object is destroyed before calling the nn::http::Finalize
function.
Error handling is the same as for matchmaking. For more information, see Section 4.25 Error Handling. The errors that can occur with data stores are listed in Table 6.19. This table excludes shared errors that occur during NEX communication, and so on.
ReturnCode Value |
Description |
---|---|
QERROR(DataStore, Unknown) |
Unknown error. This error could be caused by an unexpected server error. |
QERROR(DataStore, InvalidArgument) |
Invalid argument. This error is caused by an implementation error. |
QERROR(DataStore, PermissionDenied) |
This error occurs when you attempt to perform an operation on data for which you do not have access, or update privileges without entering a password. This error should generally never occur, because the system without access privileges should not know the data ID. One example of when this error may occur is if the system obtained the data ID by another method. Errors that must be handled by the application. |
QERROR(DataStore, NotFound) |
The data corresponding to the specified data ID or persistence slot was not found. Errors that must be handled by the application. |
QERROR(DataStore, AlreadyLocked) |
Not used. This error currently never occurs. |
QERROR(DataStore, UnderReviewing) |
Access denied because data is under review. Generated when someone other than the owner tries referencing or updating data with a data status of PENDING or REJECTED . Basically, PENDING or REJECTED data cannot be found by anyone other than the owner, so this error is not normally generated. One example of when this error may occur is if the system obtained the data ID by another method. Errors that must be handled by the application. |
QERROR(DataStore, Expired) |
Not used. This error currently never occurs. |
QERROR(DataStore, InvalidCheckToke n) |
Not used. This error currently never occurs. |
QERROR(DataStore, SystemFileError) |
Failed to read system file. This error generally never occurs. |
QERROR(DataStore, OverCapacity) |
The maximum number of items for a batch process has been exceeded. This error is caused by an implementation error. |
QERROR(DataStore, OperationNotAllowed) |
The requested operation is not authorized. This error is caused by an implementation error. |
QERROR(DataStore, InvalidPassword) |
This error occurs when you enter an incorrect password and attempt to perform an operation on data for which you do not have access or update privileges. Errors that must be handled by the application. |
QERROR(Transport, DnsError) |
This error occurs when a DNS-related error has occurred during HTTP communication with the storage server. |
QERROR(Transport, ProxyError) |
This error occurs when a proxy-related error has occurred during HTTP communication with the storage server. |
QERROR(Transport, ConnectionReset) |
This error occurs when the connection was lost during HTTP communication with the storage server. |
QERROR(Transport, Unknown) |
This error occurs when another communication error happens during HTTP communication with the storage server. |
You can use the data store management features of the NEX Game Server Management System (NMAS) to view and download the data uploaded to the data store. The tool supports both the development environment and the actual production environment.
Use the following URL to access NMAS.
https://nmas.app.nintendowifi.net/nmas/
Use the same login ID and password that you use for OMAS.
CONFIDENTIAL