Functions
[Friends Service]

Messages sent to the game service. More...


Functions
GSbool	Friends_Engine (GSuint uiMaxPostingDelay=500, GSuint uiMaxsOperationalDelay=800)
	Update connection status-messages handling relating to the friend service.
GSbool	FriendsSend_Connect ()
	This function is deprecated.
GSbool	FriendsSend_Disconnect ()
	Disconnect from the friends service.
GSbool	FriendsSend_Login (GSint lStatus=0, GSint lMood=0)
	Log into the friends service.
GSbool	FriendsSend_AddFriend (const GSchar szUsername, const GSchar szGroup, GSint iOptions)
	Add a new friend.
GSbool	FriendsSend_DelFriend (const GSchar *szUsername)
	Remove a friend from friend list.
GSbool	FriendsSend_FriendList ()
	Get all friends in friend list.
GSRESULT	FriendsSend_IgnorePlayer (const GSchar *szPlayer)
	Adds someone to the player's ignore-list.
GSRESULT	FriendsSend_UnignorePlayer (const GSchar *szPlayer)
	Removes someone to the player's ignore-list.
GSRESULT	FriendsSend_ListIgnoredPlayers ()
	Retrieves the ignore-list of the player.
GSbool	FriendsSend_PagePlayer (const GSchar szUsername, const GSchar szMessage)
	Send a page to a friend.
GSbool	FriendsSend_PeerPlayer (const GSchar szUsername, GSvoid p_Buffer, GSuint uiLength)
	Send data to a friend.
GSbool	FriendsSend_StatusChange (GSint iStatus, GSint iMood)
	Change the player status.
GSbool	FriendsSend_ChangeFriend (const GSchar szUsername, const GSchar szGroup, GSint iOptions)
	Change friend properties.
GSbool	FriendsSend_SearchPlayer (const GSchar szUsername, const GSchar szSurName, const GSchar szFirstName, const GSchar szCountry, const GSchar szEmail, GSint iSex, const GSchar szGame)
	Search for a player.
GSbool	FriendsSend_GetPlayerScores (const GSchar *szUsername)
	Get player score.

Detailed Description

These function are used to send friend-related messages to the server

Function Documentation

GSbool Friends_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 friend service. This function should be called regularly to ensure that the application will run smoothly.

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 problem with the communication of messages 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 FriendsSend_AddFriend ( const GSchar * szUsername,

const GSchar * szGroup,

GSint iOptions

)

Description:
This function is used to add a new friend to the player's friend list. These friends are stored on the server so you don't have to be stored locally.

Callbacks:
CBFriendsRcv_AddFriend CBFriendsRcv_UpdateFriend for the new friend

Returns:
Status of the function call

Return values:

GS_TRUE Successfully added new friend

GS_FALSE Failure when added new friend

Parameters:

szUsername The username of the player that will be added

szGroup The group to which the player will be added. This is just a string so that is saved for the friend. You can have any number of groups.

iOptions Friend options. See define.h

GSbool FriendsSend_ChangeFriend ( const GSchar * szUsername,

const GSchar * szGroup,

GSint iOptions

)

Description:
This function is used to change friend properties like options or the group he is in.

Callbacks:
CBFriendsRcv_UpdateFriend will have the updated info.

Returns:
Status of the function call

Return values:

GS_TRUE Success

GS_FALSE Failure

Parameters:

szUsername username of the friend

szGroup New group of the player

iOptions Friend options

GSbool FriendsSend_Connect ( )

Description:
You don't need to call this function anymore to connect to the friends service. See FriendsSend_Login()

Returns:
Status of the function call

Return values:

GS_TRUE Successfully connected to the friends service

GS_FALSE Failure to connect to the friends service

GSbool FriendsSend_DelFriend ( const GSchar * szUsername )

Description:
This function is used to remove a friend from the player's friend list

Callbacks:
CBFriendsRcv_DelFriend

Returns:
Status of the function call

Return values:

GS_TRUE Successfully removed friend

GS_FALSE Failure when removing friend

Parameters:

szUsername username of the friend we want to remove

GSbool FriendsSend_Disconnect ( )

Description:
This function is used to disconnect from the friends service

Returns:
Status of the function call

Return values:

GS_TRUE Successfully disconnect from the friends service

GS_FALSE Failure to disconnect from the friends service

GSbool FriendsSend_FriendList ( )

Description:
This function is used to get the list of friends that are in our friend list. This normally doesn't have to be called because the server pushes the CBFriendsRcv_UpdateFriend callbacks to the client. If client for some reason forgets the list of friends they have this function can called to force an CBFriendsRcv_UpdateFriend for all their friends.

Callbacks:
CBFriendsRcv_UpdateFriend for every friend

Returns:
Status of the function call

Return values:

GS_TRUE Success

GS_FALSE Failure

GSbool FriendsSend_GetPlayerScores ( const GSchar * szUsername )

Description:
DEPRECATED: This function has been replaced by the Ladder Query Service

Callback:
CBFriendsRcv_ScoreCard

Returns:
Status of the function call

Return values:

GS_TRUE Success

GS_FALSE Failure

Parameters:

szUsername Username of the player we want to get the score from.

GSRESULT FriendsSend_IgnorePlayer ( const GSchar * szPlayer )

Description:
This function adds a ubi.com username to the player's ignore-list. When someone is on a player's ignore-list, it cannot send pages or peer-messages to the player ignoring it. The ignore-list is stored remotely on the servers.
To use this function successfully, you needs to be logged in to ubi.com and to the Friends service.

Callbacks:
CBFriendsRcv_IgnorePlayer 

Parameters:

szPlayer The ubi.com username of the player to ignore (case-insensitive)

Returns:
Result code of the operation

Return values:

GSS_OK There was no error

GSE_NOTINITIALIZED The library needs to be initialised

GSE_UNEXPECTED The user is not logged in to ubi.com

GSE_BADMODE The user is not logged in to the Friends service

GSE_BADARG The szPlayer argument is NULL or empty

GSRESULT FriendsSend_ListIgnoredPlayers ( )

Description:
This function gets the remotely stored ignore-list of a player
To use this function successfully, you needs to be logged in to ubi.com and to the Friends service.

Callbacks:
CBFriendsRcv_ListIgnoredPlayers CBFriendsRcv_IgnoredPlayer 

Returns:
Result code of the operation

Return values:

GSS_OK There was no error

GSE_NOTINITIALIZED The library needs to be initialised

GSE_UNEXPECTED The user is not logged in to ubi.com

GSE_BADMODE The user is not logged in to the Friends service

GSbool FriendsSend_Login ( GSint lStatus = 0,

GSint lMood = 0

)

Description:
This function is used to log into the friends service. See define.h for the list of statuses.

Callbacks:
CBFriendsRcv_LoginResult CBFriendsRcv_UpdateFriend for all your friends

Returns:
Status of the function call

Return values:

GS_TRUE Successfully logged into the friends service

GS_FALSE Failure to log into the friends service

Parameters:

lStatus Status of the player (default at 0)

lMood Mood of the player (default at 0)

GSbool FriendsSend_PagePlayer ( const GSchar * szUsername,

const GSchar * szMessage

)

Description:
This function is used to send a page to a player. If the player isn't online the message will be saved and sent to them the next time they login to the friends service.

Callbacks:
CBFriendsRcv_PagePlayer telling you if the message was sent. CBFriendsRcv_Page is sent to the other player

Returns:
Status of the function call

Return values:

GS_TRUE Success

GS_FALSE Failure

Parameters:

szUsername The username of the recipient player

szMessage The actual message

GSbool FriendsSend_PeerPlayer ( const GSchar * szUsername,

GSvoid * p_Buffer,

GSuint uiLength

)

Description:
This function is used to send binary data to a friend. You can only send peer messages to players that are have the same client version as you.

Callbacks:
CBFriendsRcv_PeerPlayer CBFriendsRcv_PeerMsg is sent to the other player

Returns:
Status of the function call

Return values:

GS_TRUE Success

GS_FALSE Failure

Parameters:

szUsername Username of the recipient player of the data.

p_Buffer Data buffer.

uiLength Lenght of the buffer.

GSbool FriendsSend_SearchPlayer ( const GSchar * szUsername,

const GSchar * szSurName,

const GSchar * szFirstName,

const GSchar * szCountry,

const GSchar * szEmail,

GSint iSex,

const GSchar * szGame

)

Description:
This function is used to search a player in the database. Any of the arguments can be left blank, the server will return a list of matching player that as the search pattern.

Callback:
CBFriendsRcv_SearchPlayer

Returns:
Status of the function call

Return values:

GS_TRUE Success

GS_FALSE Failure

Parameters:

szUsername username of the player

szSurName Player last name

szFirstName Player first name

szCountry Player's country

szEmail Player's email

iSex Player's gender

szGame Player's favorite game

GSbool FriendsSend_StatusChange ( GSint iStatus,

GSint iMood

)

Description:
This function is used to set a new status and mood for the current player.

Callbacks:
CBFriendsRcv_StatusChange CBFriendsRcv_UpdateFriend is sent to anyone who has the player as friend.

Returns:
Status of the function call

Return values:

GS_TRUE Success

GS_FALSE Failure

Parameters:

iStatus New status of the player

iMood New mood of the player

GSRESULT FriendsSend_UnignorePlayer ( const GSchar * szPlayer )

Description:
This function removes a ubi.com username to the player's ignore-list.
To use this function successfully, you needs to be logged in to ubi.com and to the Friends service.

Callbacks:
CBFriendsRcv_UnignorePlayer 

Parameters:

szPlayer The ubi.com username of the player to remove from the ignore-list (case-insensitive)

Returns:
Result code of the operation

Return values:

GSS_OK There was no error

GSE_NOTINITIALIZED The library needs to be initialised

GSE_UNEXPECTED The user is not logged in to ubi.com

GSE_BADMODE The user is not logged in to the Friends service

GSE_BADARG The szPlayer argument is NULL or empty

Functions [Friends Service]

Functions

Detailed Description

Function Documentation

Functions
[Friends Service]