DWC_RnkGetScoreAsync

Syntax

#include <dwc.h>
DWCRnkError DWC_RnkGetScoreAsync(DWCRnkGetMode mode,
                                 u32 category,
                                 DWCRnkRegion region,
                                 DWCRnkGetParam *param);

Arguments

mode The retrieval mode.
category Category ID for identifying rankings (category ID is a numeric value ranging from zero to DWC_RNK_CATEGORY_MAX).
region The region code. Specified inside DWCRnkRegion. Specify a logical OR value when collecting data from multiple regions (for example, Japan and Europe: (DWC_RNK_REGION_JP|DWC_RNK_REGION_EU)).
param The parameter that provides detailed information about acquisition. The value specified in the structure will differ depending on the retrieval mode. For more details, see the DWCRnkGetParam structure.

Return Values

DWC_RNK_SUCCESS Succeeded.
DWC_RNK_IN_ERROR An error is being generated.
DWC_RNK_ERROR_GET_NOTREADY Communications could not be prepared.
DWC_RNK_ERROR_INVALID_PARAMETER Invalid parameter.
DWC_RNK_ERROR_GET_INVALID_KEY Invalid encryption key.
DWC_RNK_ERROR_GET_NOMEMORY Insufficient memory.

Description

Starts the asynchronous process for retrieving scores. Only one asynchronous process can be run at a time. DWC_RNK_ERROR_PUT_NOTREADY is returned if an attempt is made to execute more than one asynchronous process.

Make periodic calls to the DWC_RnkProcess function during the asynchronous process. During the process, DWC_RnkProcess returns DWC_RNK_SUCCESS.

Call the DWC_RnkGetState function to get the state of progress for the asynchronous process.

Be sure to make backups as necessary when executing asynchronous processes in succession because some members inside the DWCRnkData structure obtained using the DWC_RnkResGetRow function directly access the receive buffer.

Values that can be specified for the mode argument and the information that is retrieved as a result:
DWC_RNK_GET_MODE_ORDERGets the local host's ranking. The DWC_RnkResGetOrder function gets the result.
DWC_RNK_GET_MODE_TOPLISTGets a list of the top rankings. Gets the number of rows in the list obtained with DWC_RnkResGetRowCount and then gets the score information by calling DWC_RnkResGetRow for every row.
DWC_RNK_GET_MODE_NEAR_HIGets a list of nearby rankings that are higher than one's own ranking. Gets the number of rows in the list obtained with DWC_RnkResGetRowCount and then gets the score information by calling DWC_RnkResGetRow for every row. The local host's own data is added to the top of the list.
DWC_RNK_GET_MODE_NEAR_LOWGets a list of nearby rankings that are lower than one's own ranking. Gets the number of rows in the list obtained with DWC_RnkResGetRowCount and then gets the score information by calling DWC_RnkResGetRow for every row. The local host's own data is added to the top of the list.
DWC_RNK_GET_MODE_NEARGets a list of nearby rankings, consisting of the specified number of entries arranged with the closest scores first. Gets the number of rows in the list obtained with DWC_RnkResGetRowCount and then gets the score information by calling DWC_RnkResGetRow for every row. The local host's own data is added to the top of the list.
DWC_RNK_GET_MODE_FRIENDSGets a list of rankings among the local host's friends (the maximum number of PIDs that may be specified is DWC_RNK_FRIENDS_MAX (64)). Gets the number of rows in the list obtained with DWC_RnkResGetRowCount and then gets the score information by calling DWC_RnkResGetRow for every row. The local host's own data is added to the top of the list.

When exchanging information that is limited to friends, such as free word communication or anything making use of user-defined data, you must observe the Guidelines and verify the existence of an established friend relationship before displaying the information.

Revision History

For the changelog prior to 5.1 PR2, click here.


CONFIDENTIAL