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