#include <dwc.h>
BOOL DWC_UpdateServersAsync(
const char* reserved,
DWCUpdateServersCallback updateCallback,
void* updateParam,
DWCFriendStatusCallback statusCallback,
void* statusParam,
DWCDeleteFriendListCallback deleteCallback,
void* deleteParam );
Synchronizes the GameSpy server and local friend rosters. To perform this synchronization process, first use the DWC_LoginAsync function to complete everything up until the login.
Set the friend roster in advance by using the DWC_InitFriendsMatch function. For precautions on editing friend rosters, see the DWC_CreateExchangeToken function description.
The friend roster synchronization process involves the following three main tasks:
Even if the partner who is sent the friend relationship request is offline, the request is saved on the GameSpy server and is delivered after the partner logs in using the DWC_LoginAsync function. The friend relationship is established only when the partner also has this information on his local friend roster. However, this only registers the partner as a friend on the DS of the person sending the request. Partners that receive friend relationship requests automatically follow the same process to register the requesting party as a friend.
The request to build a friend relationship is sent only once to each partner during each login session.
Bear in mind that the friend roster synchronization process completion callback is called only after all the local and GameSpy server friend rosters are checked, the necessary friend relationship requests are sent, and the unnecessary friend information is deleted. Even though a callback has been returned, it does not mean that all friend relationships have been established.
When the isChanged argument of the friend roster synchronization process completion callback is TRUE, this indicates that some of the friend information in the local friend roster has been updated and the local friend roster must be saved. If friend relationships are established outside of the friend roster synchronization process, the configured friend relationship establishment callback is called with the DWC_SetBuddyFriendCallback function.
Also, if multiple friend information entries about the same friend are found in the roster during the friend roster synchronization process, all except one of them will be deleted. A callback is invoked for each deletion, with the deleted friendship information entry's index in the friend roster, and the index of what was determined to be identical information, passed as arguments.
Although, in principle, the entry with a smaller index will remain, in the event that a friend relationship has been established for one entry and not the other, the former will remain. A redundancy check is also performed when a friend relationship has been established. In this case, as well, the entry with the smallest index will remain (furthermore, when the data types of the redundant friend information entries are a friend registration key and a GS profile ID, it is changed to the GS profile ID).
reserved |
Specify NULL. Retained for compatibility with past versions. |
updateCallback |
Pointer to the friend roster synchronization process completion callback function. |
updateParam |
Parameter for the friend roster synchronization process completion callback. |
statusCallback |
Pointer to the callback function that notifies the user about changes to friend status. Even if the friend roster synchronization process has completed, this callback function is called each time there are changes to a friend's communication status. |
statusParam |
Parameter for the callback that notifies the user about changes to friend status. |
deleteCallback |
Pointer to the callback function that deletes information from the friend roster. Even if the friend roster synchronization process has completed, there is the possibility that this callback function may be called when a friend relationship is established. |
deleteParam |
Parameter for friend roster deletion callback. |
TRUE |
Start the friend roster synchronization process. The results are indicated via the callback function. |
FALSE |
Not a good state for calling this function. |
DWC_InitFriendsMatch
DWC_CreateExchangeToken
DWC_SetBuddyFriendCallback
DWCUpdateServersCallback
DWCFriendStatusCallback
DWCDeleteFriendListCallback
DWC_IsBuddyFriendData
DWC_WasBuddyFriendData
2008/01/11 Added text about the timing of transmissions of the requests to build friend relationships.
2007/07/21 Added details about the deletion of duplicate friend information.
2005/12/16 Added details about the friend roster synchronization process.
2005/11/01 Made revisions.
2005/07/22 Initial version.
CONFIDENTIAL