6. Data Stores

6.1. Introduction

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.

  • Using only the game server (storage server not used)

    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.

  • Using the game server and storage server

    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.

6.2. Overall Flow of Data Stores

A data store uses the following overall flow.

  1. Log in to the game server.
  2. Initialize the HTTP library. (This process is not required if you are only using the game server.)
  3. Initialize the service client.
  4. Upload data. As necessary, use features to download, update, delete, search, and evaluate data, and get and edit meta-information.
  5. Finalize the HTTP library. (This process is not required if you are only using the game server.)
  6. Finalize the service client, and log out from the game server.

6.3. Initialization and Finalization

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();

6.4. Uploading Data

Use the DataStoreClient::PostObject function to upload data. The following methods for uploading data are available.

Using only the game server

Using the game server and the storage server

Two upload methods are available.

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.

  • Data IDs are assigned in order, starting with 1.
  • Data ID values continually increase.

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.

Table 6.1 DataStorePostParam Parameters
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::NUM_TAG_SLOT 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

6.4.1. Data Types

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.

6.4.2. Privileges and Passwords

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.

Table 6.2 Privilege Types
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.

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.

6.4.3. Tags

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);

6.4.4. Initializing Ratings

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.)

Table 6.4 DataStoreRatingInitParam Parameters
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
Table 6.5 Rating Option Flags
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.

  • Set with the 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.

  • Set with the 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.

  • Set with the 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.

  • Set with the 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);

6.4.5. Meta-binaries

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);

6.4.6. Settings Flags

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.

Table 6.6 Settings Flags
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.

6.4.7. Batch Uploading

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.

6.4.8. Uploading With a Specific Data ID

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.

  • The specified data ID must be between 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.
  • The data can only be used by the game server and cannot be uploaded to a storage server.
  • The owner ID is set to the principal ID for the system (2). The principal ID of the uploader is not applied.
  • The data does not expire and cannot be deleted.
  • Access and update permissions are fixed at DataStoreConstants::PERMISSION_PUBLIC.
  • Data cannot be deleted using the DataStoreClient::DeleteObject function. Use NMAS if the data needs to be deleted.
  • Data cannot be updated using the DataStoreClient::ChangeMeta function. (Support to be added at a later date.)
  • Tags cannot be assigned.
  • Cannot be set in a persistence slot.

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.

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.

  • Batch processing

    You can specify multiple data IDs and upload multiple data items. Up to BATCH_PROCESSING_CAPACITY_POST_OBJECT IDs can be specified.

  • Runtime errors

    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.

6.5. Downloading Data

Use the DataStoreClient::GetObject function to download uploaded data. The following methods for downloading data are available.

  • Method of specifying the buffer directly in the parameter

    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.

  • Using an event listener

    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.

6.6. Updating Data

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.

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.

6.7. Deleting Data

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.

6.7.1. Batch Processing

You can delete uploaded data as a batch process. Use the DataStoreClient::DeleteObject function in the same way as when you make individual deletions.

6.9. Displaying Data IDs

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.

6.10. Rating Data

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.

  • Calculating ratings total values

    Use the DataStoreClient::RateObject function to calculate ratings total values. When initializing ratings, only the provided slot can be rated.

  • Get ratings information

    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.

  • Resetting ratings information

    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.

6.10.1. Batch Processing

  • Batch ratings

    Use the DataStoreClient::RateObject function in the same way as when you rate individual objects.

  • Getting rating information as a batch process

    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.

  • Resetting ratings information as a batch process

    As with resetting a single rating, use the DataStoreClient::ResetRating function to reset multiple ratings.

Table 6.9 Information That Can Be Obtained With DataStoreRatingInfo
Name Get Function
The total value of the rating GetTotalValue
Number of times rated GetCount
Initial value for the ratings total value GetInitialValue
Table 6.10 Information That Can Be Obtained With DataStoreRatingLog
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

6.11. Updating Data Access Dates, Times, and Counts

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.

6.12. Getting Metadata

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.

Table 6.11 Information That Can Be Obtained With DataStoreMetaInfo
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

6.12.1. Batch Processing

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.

6.13. Updating Metadata

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.

Table 6.12 Metadata Update Flags
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::MODIFICATION_FLAG_DATA_TYPE Changes the data type.
DataStoreConstants::MODIFICATION_FLAG_REFERRED_CNT Changes the reference count. (Do not use.)
DataStoreConstants::MODIFICATION_FLAG_STATUS Changes the status.

6.13.1. Batch Processing

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.

6.13.2. Compare and Swap

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).

Table 6.13 Metadata Comparison Flags
Flags Description
DataStoreConstants::COMPARISON_FLAG_NONE Not set.
DataStoreConstants::COMPARISON_FLAG_NAME Compare titles.
DataStoreConstants::COMPARISON_FLAG_ACCESS_PERMISSION Compare access permission.
DataStoreConstants::COMPARISON_FLAG_UPDATE_PERMISSION Compare update permission.
DataStoreConstants::COMPARISON_FLAG_PERIOD Compare the number of days in the valid period.
DataStoreConstants::COMPARISON_FLAG_METABINARY Compare binary data.
DataStoreConstants::COMPARISON_FLAG_TAGS Compare tags.
DataStoreConstants::COMPARISON_FLAG_DATA_TYPE Compare the data type.
DataStoreConstants::COMPARISON_FLAG_REFERRED_CNT Compare the reference count. (Do not use.)
DataStoreConstants::COMPARISON_FLAG_STATUS Compare status.
DataStoreConstants::COMPARISON_FLAG_ALL Compare all.

6.14. Linking to SpotPass

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.

When using this function on the CTR, keep the data ID so that it does not exceed a range of 32 bits.

6.14.1 Uploading

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.

Table 6.14 Game Server Setting Parameters for Uploading Using SpotPass
Name Values That Can Be Configured Settings Function
Game Server ID Issued by OMAS. nn::boss::DataStoreUploadAction::Initialize()
Access key. Issued by OMAS. nn::boss::DataStoreUploadAction::Initialize()

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.

Table 6.15 Parameters for Data Uploaded Using SpotPass
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::boss::DataStoreUploadAction::Initialize()
Access privileges
nn::boss::DstKind_FRIEND (DataStoreConstants::PERMISSION_FRIEND or equivalent)
nn::boss::DstKind_SPECIFIED (DataStoreConstants::PERMISSION_SPECIFIED or equivalent)
nn::boss::DstKind_SPECIFIED_FRIEND (DataStoreConstants::PERMISSION_SPECIFIED_FRIEND or equivalent)

When specifying nn::boss::DstKind_SPECIFIED or nn::boss::DstKind_SPECIFIED_FRIEND, the destination principal ID must be specified. You can specify up to 100 items.
nn::boss::DataStoreUploadAction::Initialize and nn::boss::DataStoreUploadAction::AddDstPrincipalId
Update permissions DataStorePermission( DataStoreConstants::PERMISSION_PRIVATE ) None.
Configuration flag DataStoreConstants::DATA_FLAG_USE_NOTIFICATION_ON_POST None.
The number of valid days 1–365 nn::boss::DataStoreUploadAction::Initialize()
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.

6.14.2. Downloads

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.

Table 6.16 Game Server Setting Parameters for Downloading Using SpotPass
Name Values That Can Be Configured Settings Function
Game Server ID Issued by OMAS. nn::boss::DataStoreDownloadAction::Initialize()
Access key. Issued by OMAS. nn::boss::DataStoreDownloadAction::Initialize()

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.

Table 6.17 Game Server Setting Parameters for Downloading Using SpotPass
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.

6.15. Perpetuating Data

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.

  • All players can save their data ID storing their profile information to persistence slot ID 0. When people meet over the network, they can get each other's player information from persistence slot ID 0. Using this procedure eliminates the need to exchange another separate data ID, and the data is always guaranteed to be there.
  • When uploading scores using the ranking library, score-related information can be uploaded to a separate data store and made persistent, and that persistence slot ID can be stored to a ranking parameter. Using this procedure, only data from the data store gets registered to the ranking, and you can avoid inconsistencies that can arise when data expires.

6.15.1. Perpetuating Data

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.

6.15.2. Unperpetuating Data

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.

6.15.3. Getting Persistence Information

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.

6.16. Getting Passwords

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.

6.17. Common Data Store Specifications

6.17.1. Data Status

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.

Table 6.18 Data Status
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.

6.17.2. Changing Timestamp Values

Figure 6.2 Changing Timestamp Values When Using the API shows how timestamp values are changed when using the different data store functions.

_images/Fig_Datastore_Timestamp.png

Figure 6.2 Changing Timestamp Values When Using the API

6.17.3. Notes About Batch Processing

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.

6.17.4. Cautions During HTTP Communications

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.

6.18. Error Handling

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.

Table 6.19 Data Store Errors
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, InvalidCheckToken) 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.

6.19. NEX Server Management System (NMAS)

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.

6.19.1. Accessing NMAS

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