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 from inside `DWCRnkRegion`. Specify an OR value when collecting data from multiple regions (Example: For Japan and Europe (`DWC_RNK_REGION_JP`\|`DWC_RNK_REGION_EU`)).
param	Parameter that specifies detailed information in order to perform retrieval. 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 occurring.
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 obtaining the score. 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 of the asynchronous process.

Be sure to make backups as necessary when executing asynchronous processes in succession because some members inside the DWCRnkDatastructure 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_ORDER

Gets the order. The results are obtained with DWC_RnkResGetOrder.

DWC_RNK_GET_MODE_TOPLIST

Gets the top of the ranking list. Gets the number of rows in the list obtained using DWC_RnkResGetRowCount and calls DWC_RnkResGetRow for each row to get score information.

DWC_RNK_GET_MODE_NEAR_HI

Gets a list of nearby rankings that are higher than one's own ranking. Gets the number of rows in the list obtained using DWC_RnkResGetRowCount and calls DWC_RnkResGetRow for each row to get score information. One's own data is added to the top of the list.

DWC_RNK_GET_MODE_NEAR_LOW

Gets a list of nearby rankings that are lower than one's own ranking. Gets the number of rows in the list obtained using DWC_RnkResGetRowCount and calls DWC_RnkResGetRow for each row to get score information. One's own data is added to the top of the list.

DWC_RNK_GET_MODE_NEAR

Gets a list of rankings near one's own. Gets the number of rows in the list obtained using DWC_RnkResGetRowCount and calls DWC_RnkResGetRow for each row to get score information. One's own data is added to the top of the list.

DWC_RNK_GET_MODE_FRIENDS

Gets a list of rankings among one's friends (the maximum number of PIDs that may be specified is DWC_RNK_FRIENDS_MAX (64)). Uses the DWC_RnkResGetRowCount function to get the number of rows in the list, then gets the score information by calling the DWC_RnkResGetRow function for every row. One's own data is added to the top of the list.

To exchange information that is limited to friends, such as free word communication that contains user-defined data, the friend relationship must be verified before displaying the information based on the guidelines.

Revision History

1.4.5: Added DWC_RNK_GET_MODE_HI.
Added DWC_RNK_GET_MODE_LOW.
1.4.8: Corrected text, changing "the score is higher/lower than one's own" to "the ranking is higher/lower than one's own", and deleted the text "Lists starting with data closest to your own score" from Nearby Rankings.

CONFIDENTIAL

Values that can be specified for the `mode` argument, and the information that is retrieved as a result:
DWC_RNK_GET_MODE_ORDER	Gets the order. The results are obtained with `DWC_RnkResGetOrder`.
DWC_RNK_GET_MODE_TOPLIST	Gets the top of the ranking list. Gets the number of rows in the list obtained using `DWC_RnkResGetRowCount` and calls `DWC_RnkResGetRow` for each row to get score information.
DWC_RNK_GET_MODE_NEAR_HI	Gets a list of nearby rankings that are higher than one's own ranking. Gets the number of rows in the list obtained using `DWC_RnkResGetRowCount` and calls `DWC_RnkResGetRow` for each row to get score information. One's own data is added to the top of the list.
DWC_RNK_GET_MODE_NEAR_LOW	Gets a list of nearby rankings that are lower than one's own ranking. Gets the number of rows in the list obtained using `DWC_RnkResGetRowCount` and calls `DWC_RnkResGetRow` for each row to get score information. One's own data is added to the top of the list.
DWC_RNK_GET_MODE_NEAR	Gets a list of rankings near one's own. Gets the number of rows in the list obtained using `DWC_RnkResGetRowCount` and calls `DWC_RnkResGetRow` for each row to get score information. One's own data is added to the top of the list.
DWC_RNK_GET_MODE_FRIENDS	Gets a list of rankings among one's friends (the maximum number of PIDs that may be specified is `DWC_RNK_FRIENDS_MAX` (64)). Uses the `DWC_RnkResGetRowCount` function to get the number of rows in the list, then gets the score information by calling the `DWC_RnkResGetRow` function for every row. One's own data is added to the top of the list.