#include <dwc.h>
BOOL DWC_UpdateServersAsync(const char *playerName,
DWCUpdateServersCallback updateCallback,
void *updateParam,
DWCFriendStatusCallback statusCallback,
void *statusParam,
DWCDeleteFriendListCallback deleteCallback,
void *deleteParam);| playerName | 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 friend roster synchronization has completed, this callback function is called each time there are changes to a friend's communication status. The callback function can also be set using the DWC_SetFriendStatusCallback function. Note that this function and the DWC_SetFriendStatusCallback function each rewrite the callback set by the other. |
| 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. |
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.
The friend roster synchronization process involves the following three main tasks.
Even if the partner who sent the friend relationship request is offline, the request is saved on the GameSpy server and is delivered after the partner next 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 Nintendo DS system 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.
Because friend roster synchronization requires communication with the GameSpy server, implementations where each client periodically calls this function will result in a high load on the server. As a guide, after calling this function upon login, limit calls to only those cases where the application changes the friend roster or where it is necessary to confirm whether the other party is maintaining a friend relationship.
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 the friend roster synchronization process, the friend relationship establishment callback set with the DWC_SetBuddyFriendCallback function is called.
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. However, it is not possible to confirm the sameness of friend information entries for friends that have not connected to Wi-Fi connection (DWC_FRIENDDATA_LOGIN_ID) with those for friends that have connected (DWC_FRIENDDATA_FRIEND_KEY/DWC_FRIENDDATA_GS_PROFILE_ID), so some friend information entries that are actually identical are not deleted. A callback is invoked for each deletion, with the deleted friendship information entry's index in the friend roster and the index of the friend who was determined to have identical information passed as arguments.
Although, in principle, the entry with a smaller index remains, in the event that a friend relationship has been established for one entry and not the other, the former remains. A redundancy check is also performed when a friend relationship has been established. In this case as well, the entry with the smallest index remains. Also, 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.
Once friend roster synchronization has started, you cannot call the DWC_CloseAllConnectionsHard or DWC_ShutdownFriendsMatch function until the completion callback for friend roster synchronization is invoked. In particular, calling the DWC_ShutdownFriendsMatch function results in a memory leak.
No procedure has been prepared for canceling this function, so after calling this function wait for the callback to return.
Do not call this function during matchmaking.
DWC_CloseAllConnectionsHard or DWC_ShutdownFriendsMatch function during friend roster synchronization.statusCallback is overwritten by the DWC_SetFriendStatusCallback function. For the change log before 5.1 PR2, click here.
CONFIDENTIAL