Main Page | Modules | Class List | File List | Class Members | File Members

Functions
[Ladder Query Service]

Messages sent to the ladder query service. More...

Functions

GSbool LadderQuery_Initialize (GSchar *szLocale)
 Initialization function for the ladder query service.

GSbool LadderQuery_Uninitialize ()
 Uninitialization function for the ladder query service.

GSbool LadderQuery_Engine (GSuint uiMaxPostingDelay=500, GSuint uiMaxsOperationalDelay=800)
 Update connection status related to the ladder query service.

GSbool LadderQuery_CreateRequest (GSchar *szGameName, GSuint uiEvent=0, GSuint uiMode=0)
 Create a basic ladder query request.

GSuint LadderQuery_SendRequest ()
 Send a request over the network.

GSbool LadderQuery_RequestPivotUser (const GSchar *pszEntry, GSuint uiNumberOfEntries)
 Requesting an ordered list of entries around a pivot (username).

GSbool LadderQuery_RequestPivotRow (GSuint uiRowNumber, GSuint uiNumberOfEntries)
 Requesting an ordered list of entries around a pivot (row number).

GSbool LadderQuery_RequestSet (const GSchar *pszEntries[], GSuint uiNumberOfEntries)
 Requesting a pre-defined set of entries.

GSbool LadderQuery_RequestOrderedList (GSuint uiFirstEntry, GSuint uiNumberOfEntries)
 Requesting an ordered list of entries from a starting index (row number).

GSbool LadderQuery_AddSortConstraint (const GSchar *pszField, GSbool bSortDirection)
 Add a sort constraint to a created request.

GSbool LadderQuery_AddFilterConstraint (const LADDER_FILTER *pLadderFilter[], GSuint uiListOfFilters)
 Add a filter constraint to a created request.

GSbool LadderQuery_AddDisplayConstraint (const GSchar *pszFields[], GSuint uiNumberOfFields)
 Add a display constraint to a created request.

Detailed Description

These functions are used to send request to the ubi.com data provider and retrieve results when a reply is given by the server.

Function Documentation

GSbool LadderQuery_AddDisplayConstraint (  const GSchar *  pszFields[],
GSuint  uiNumberOfFields
) 
 

Description:
This function set a display constraint to a request that has been created. Display constraint will make the results contain only the supplied list of fields.
Returns:
Status of the function call
Return values:
GS_TRUE Success
GS_FALSE Failure
Parameters:
pszFields A pointer to an array of string values (fields).
uiNumberOfFields The size of the array of string values.

GSbool LadderQuery_AddFilterConstraint (  const LADDER_FILTER *  pLadderFilter[],
GSuint  uiListOfFilters
) 
 

Description:
This function set a filter constraint to a request that has been created. Filters are defined using the LADDER_FILTER structure.
Returns:
Status of the function call
Return values:
GS_TRUE Success
GS_FALSE Failure
Parameters:
pLadderFilter A pointer to an array of ladder filter.
uiListOfFilters The size of the array of ladder filter.

GSbool LadderQuery_AddSortConstraint (  const GSchar *  pszField,
GSbool  bSortDirection
) 
 

Description:
This function set a sort constraint to a request that has been created.
Returns:
Status of the function call
Return values:
GS_TRUE Success
GS_FALSE Failure
Parameters:
pszField The field name to sort by.
bSortDirection The sort direction where GS_TRUE = natural order and GS_FALSE = unnatural order.

GSbool LadderQuery_CreateRequest (  GSchar *  szGameName,
GSuint  uiEvent = 0,
GSuint  uiMode = 0
) 
 

Description:
This function creates a basic ladder query request (ordered list, with no constraint) that can be sent over the network to the ubi.com data provider. The LadderQuery_CreateRequest() function should be called each time you want to make a request. Once the request is created, you can tell which type of request you want, and optionally add one or more constraint. If you call this function again before sending the request created previously, the type and constraint of the previous request are overwritten by the default ones.
NOTE: This function will return GS_FALSE if you have not completed the login sequence on the gs-router server.

Returns:
Status of the function call
Return values:
GS_TRUE Success
GS_FALSE Failure
Parameters:
szGameName The game name associated with the requested ladder data.
uiEvent The event id associated with the ladder data.
uiMode The game mode.

GSbool LadderQuery_Engine (  GSuint  uiMaxPostingDelay = 500,
GSuint  uiMaxsOperationalDelay = 800
) 
 

Description:
Updates the connection between the client and the server, and handles the delivery of queued up messages and reception of messages relating to the ladder query service service. This function should be called regularly to ensure that the service will run smoothly and properly.
Returns:
Status of the function call
Return values:
GS_TRUE The connection is ok and function call was a success
GS_FALSE There has been a communication problem between the client and the server
Parameters:
uiMaxPostingDelay The maximum time to be spent inside the engine to read incomming messages and posting them to the message queue. (Milliseconds)
uiMaxsOperationalDelay The maximum time to be spent inside the engine to decode message in the queue and calling appropriate callback. (Milliseconds)

GSbool LadderQuery_Initialize (  GSchar *  szLocale  ) 
 

Description:
This function takes a 2 character string argument that represent the locale in which the string results will be returned from the server.
The initialisation of the ladder query service can be done after the client library initialization (i.g. GSClientLibrary_Initialize())

Returns:
Status of the function call
Return values:
GS_TRUE Success
GS_FALSE Failure
Parameters:
szLocale The locale in which the string results will be returned from the server.

GSbool LadderQuery_RequestOrderedList (  GSuint  uiFirstEntry,
GSuint  uiNumberOfEntries
) 
 

Description:
This function set the request mode to retrieve an ordered list of entries from a starting zero-based index representing a row number.
Returns:
Status of the function call
Return values:
GS_TRUE Success
GS_FALSE Failure
Parameters:
uiFirstEntry Zero-based index of the first entry to get.
uiNumberOfEntries Total number of entries in the array of values.

GSbool LadderQuery_RequestPivotRow (  GSuint  uiRowNumber,
GSuint  uiNumberOfEntries
) 
 

Description:
This function set the request mode to retrieve an ordered list of entries around a pivot where the pivot is a row number in the ladder.
Returns:
Status of the function call
Return values:
GS_TRUE Success
GS_FALSE Failure
Parameters:
uiRowNumber The row number used as a pivot.
uiNumberOfEntries Total number of entries to retrieve.

GSbool LadderQuery_RequestPivotUser (  const GSchar *  pszEntry,
GSuint  uiNumberOfEntries
) 
 

Description:
This function set the request mode to retrieve an ordered list of entries around a pivot where the pivot is a user name entry.
Returns:
Status of the function call
Return values:
GS_TRUE Success
GS_FALSE Failure
Parameters:
pszEntry Pointer to a character string representing the username to use as a pivot.
uiNumberOfEntries Total number of entries to retrieve.

GSbool LadderQuery_RequestSet (  const GSchar *  pszEntries[],
GSuint  uiNumberOfEntries
) 
 

Description:
This function set the request mode to retrieve a pre-defined set of entries supplied by the caller.
Returns:
Status of the function call
Return values:
GS_TRUE Success
GS_FALSE Failure
Parameters:
pszEntries Pointer on an array of string values. Each string values should be a username.
uiNumberOfEntries Total number of entries in the array of values.

GSuint LadderQuery_SendRequest (   ) 
 

Description:
This function send a request over the network to the ubi.com servers. This function will return the id of the sent request and in case of error it will return 0. The id of the request will be used once we get the results so you have to keep it in memory.
Callbacks:
CBLadderQueryRcv_RequestReply
Returns:
The id of the request that has been sent.
Return values:
0 Internal error
else The id of the request that has been sent.

GSbool LadderQuery_Uninitialize (   ) 
 

Description:
This function uninitialize the ladder query service and free allocated memory.
Returns:
Status of the function call
Return values:
GS_TRUE Success
GS_FALSE Failure

Ubi.com GameService SDK - ©UbiSoft Entertainment 2002
GameService development team