4.2. Advanced Features of PiaInet

Application-Defined Event Notification

After logging in to the game server, you can send application-defined event notifications to friends logged in to the same game server. This event notification process can be performed by logging in to the game server and calling NexFacade::Bind().

The feature is designed with this implementation in mind, where a user logs in to the server and sends events to his or her communication partners. Do not use it for frequent transmissions. Specifically, this feature has the following restrictions.

  • It cannot be used to send data other than events from users. One example of this would be the exchange of data during an online game that was originally sent and received through P2P communication.
  • Restrict events to being sent no more than 10 times a minute to prevent successive user operations from resulting in too many transmissions.
  • Use nn::nex::NotificationEvents::GameNotificationEvent types 1 to 8 as the game-defined event types.

The event notification process is an asynchronous process. Call the NexFacade::UpdateNotificationDataAsync() function to start the asynchronous process, and use the NexFacade::IsCompletedUpdateNotificationData() function to detect the end of the asynchronous process. If sending the event to the game server has succeeded, the NexFacade::GetUpdateNotificationDataResult() function returns a result value indicating that IsSuccess() is true.

Code 4-4. Application-Defined Event Notification
/*
Already logged in to the game server and NexFacade::Bind() has been called.
*/


// Notification event parameter settings.
uint32_t param1 = 1;
uint32_t param2 = 2;
nn::nex::NotificationEvents::NotificationEvents eventType =nn::nex::NotificationEvents::GameNotificationType1;
const wchar_t stringParam[] = L"Test";

// Send notification event.
nn::pia::Result result = nn::pia::inet::NexFacade::GetInstance()->UpdateNotificationDataAsync(eventType, param1, param2, stringParam, sizeof(stringParam)/sizeof(wchar_t));
if (result.IsFailure())
{
    // Error processing.
}

// If the asynchronous process has started successfully, you must call the dispatch function periodically and wait for the asynchronous process to proceed.
while (nn::pia::inet::NexFacade::GetInstance()->IsCompletedUpdateNotificationData() == false)
{
    // You must call the Pia and NEX Scheduler::Dispatch functions.
    nn::pia::common::Scheduler::GetInstance()->Dispatch();
    nn::nex::Scheduler::GetInstance()->DispatchAll();
}

result = nn::pia::inet::NexFacade::GetInstance()->GetUpdateNotificationDataResult();
if (result.IsFailure())
{
    // Error processing.
}

Receiving Notification Events

To receive events sent from friends to the game server, declare a class that inherits nn::nex::NotificationEventHandler in your application. Then use the nn::nex::NgsFacade::RegisterNotificationEventHandler() function to register the pointer to this instance to the nn::nex::NgsFacade class instance that was used to log in to the game server. For more information about the notification event handling method in the event handler, see Server Services > Matchmaking > Handling Notification Events in the NEX Programming Manual.

The event handler will not be notified of events sent to the game server before registering the event handler. To receive events that were sent prior to registration, use the nn::pia::inet::NexFacade::RetrieveNotificationDataAsync() function. Receiving events is asynchronous processing. Call the NexFacade::RetrieveNotificationDataAsync() function to start the asynchronous process, and use the NexFacade::IsCompletedRetrieveNotificationData() function to detect the end of the asynchronous process. If sending the event to the game server has succeeded, the NexFacade::GetRetrieveNotificationDataResult() function returns a result value indicating that IsSuccess() is true.

Code 4-5. Receiving Notification Events
// Declare the event handler class.
class SampleNexNofiticationEventHandler : public nn::nex::NotificationEventHandler
{
public:
    SampleNexNofiticationEventHandler()
    {
    }
    virtual ~SampleNexNofiticationEventHandler()
    {
    }

    virtual void ProcessNotificationEvent(const nn::nex::NotificationEvent& oEvent)
    {
        PIA_SAMPLE_LOG("Received notification event. Type:%u, Param1:%d, Param2:%d\n", oEvent.GetType(), oEvent.GetParam1(), oEvent.GetParam2());
    }
};

// Event handler instance.
SampleNexNofiticationEventHandler s_NexNotificationHandler;

/*
Complete logging in to the game server in advance.
*/


// Register an event handler to receive event notifications from the game server. (Make sure that you clear this registered event handler when you log out.)
Nex_GetNgsFacadeInstance()->RegisterNotificationEventHandler(&s_NexNotificationHandler);

// Set the NEX game server information in NexFacade.
nn::pia::inet::NexFacade::LoginInfo loginInfo;
loginInfo.gameServerId = gameId;
loginInfo.pNgsFacade = pNgsFacade;

nn::pia::inet::NexFacade::GetInstance()->Bind(&loginInfo);

// Get events already sent to the game server. (Event types GameNotificationType1 through GameNotificationType4 are set here.)
nn::nex::qList<nn::nex::NotificationEvent> listNotificationEvent;

result = nn::pia::inet::NexFacade::GetInstance()->RetrieveNotificationDataAsync(0xf, &listNotificationEvent);
{
    // Error processing.
}

// If the asynchronous process has started successfully, you must call the dispatch function periodically and wait for the asynchronous process to proceed.
while (nn::pia::inet::NexFacade::GetInstance()->IsCompletedRetrieveNotificationData() == false)
{
    // You must call the Pia and NEX Scheduler::Dispatch functions.
    nn::pia::common::Scheduler::GetInstance()->Dispatch();
    nn::nex::Scheduler::GetInstance()->DispatchAll();
}

result = nn::pia::inet::NexFacade::GetInstance()->GetRetrieveNotificationDataResult();
if (result.IsFailure())
{
    // Error processing.
}

// Process the obtained event.
for (nn::nex::qList<nn::nex::NotificationEvent>::const_iterator it = listNotificationEvent.begin(); it != listNotificationEvent.end(); ++it)
{
    PIA_SAMPLE_LOG("Retrieved friend notification event. Type:%u, Param1:%d, Param2:%d\n", it->GetType(), it->GetParam1(), it->GetParam2());
}