DWC_RnkGetScoreAsync

C Specification


#include <dwc.h>

DWCRnkError    DWC_RnkGetScoreAsync( DWCRnkGetMode   mode,
u32             category,
DWCRnkRegion    region,
DWCRnkGetParam* param );
				

Description

Starts the asynchronous process for obtaining the score. Only one asynchronous process can be run at a time. If you attempt to run multiple asynchronous processes at the same time, the function will return DWC_RNK_ERROR_PUT_NOTREADY.

Make periodic calls to the DWC_RnkProcess function during the asynchronous process. During processing, DWC_RnkProcess will return DWC_RNK_SUCCESS.

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

Because the Receive buffer directly references some of the members in the DWCRnkData structure that the DWC_RnkResGetRow function gets, the use of that buffer should be avoided as much as possible when executing asynchronous processes.

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 rank order. The DWC_RnkResGetOrder function gets the result.
DWC_RNK_GET_MODE_TOPLIST Gets the top ranking list. Gets the number of rows in the list retrieved with DWC_RnkResGetRowCount, then gets the score information by calling DWC_RnkResGetRow for every row.
DWC_RNK_GET_MODE_NEAR Gets ranking lists near one's own score. Gets the number of rows in the list obtained with DWC_RnkResGetRowCount, then gets the score information by calling DWC_RnkResGetRow for every row. Enumerates data from scores that have small differences from one's own score. One's own data gets attached to the top of the list.
DWC_RNK_GET_MODE_FRIENDS Gets the ranking list from among the friends specified with the DWC_RNK_FRIENDS_MAX(64) PIDs. Gets the number of rows in the list obtained with DWC_RnkResGetRowCount, then gets the score information by calling DWC_RnkResGetRow for every row. One's own data gets attached 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.

Arguments

mode The get mode.
category The category ID for differentiating rankings (a numerical value between 0 and DWC_RNK_CATEGORY_MAX).
region The region code. Speficied from inside DWCRnkRegion. Specifies OR values to combine different regions. (For example, Japan and Europe would be: DWC_RNK_REGION_JP|DWC_RNK_REGION_EU)
param The parameter that provides detailed information regarding acquisition. The value specified in the structure will differ depending on the get 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 An invalid parameter
DWC_RNK_ERROR_GET_INVALID_KEY Invalid encryption key.
DWC_RNK_ERROR_GET_NOMEMORY Insufficient memory.

See Also

DWCRnkGetMode DWCRnkGetParam DWC_RnkGetState DWC_RnkResGetOrder DWC_RnkResGetRow DWC_RnkResGetRowCount DWC_RnkProcess DWC_RnkCancelProcess

Revision History

07/21/2006 Revised where the maximum number of friends was 32. Added guideline-related information
06/20/2006 Corrected errors
04/14/2006 Initial version


CONFIDENTIAL