IDirectPlay8Peer::GetApplicationDesc Method

DirectPlay

 
Microsoft DirectX 9.0 SDK Update (Summer 2003)

IDirectPlay8Peer::GetApplicationDesc Method


Retrieves the full application description for the connected application.

Syntax

HRESULT GetApplicationDesc(      
    DPN_APPLICATION_DESC *const pAppDescBuffer,     DWORD *const pcbDataSize,     const DWORD dwFlags );

Parameters

pAppDescBuffer
[out] Pointer to a DPN_APPLICATION_DESC structure where the application description data is to be written. Set this parameter to NULL to request only the size of data. If pAppDescBuffer is not set to NULL, you must set the pAppDescBuffer.dwSize member to an appropriate value. The pcbDataSize parameter is set to the size required to hold the data.
pcbDataSize
[in, out] Pointer to a variable of type DWORD that is initialized to the size of the buffer before calling this method. After the method returns, this parameter is set to the size, in bytes, of the session data. If the buffer is too small, this method returns the DPNERR_BUFFERTOOSMALL error value, and this parameter is set to the buffer size required. If this parameter is NULL, the method returns DPNERR_INVALIDPARAM.
dwFlags
[in] Reserved. Must be 0.

Return Value

Returns S_OK if successful, or one of the following error values.

DPNERR_BUFFERTOOSMALLThe supplied buffer is not large enough to contain the requested data.
DPNERR_INVALIDFLAGSThe flags passed to this method are invalid.
DPNERR_INVALIDPARAMOne or more of the parameters passed to the method are invalid.
DPNERR_NOCONNECTIONNo communication link was established.

Remarks

Call this method initially by passing NULL in the pAppDescBuffer parameter to obtain the size of the required buffer. When you call the method a second time to fill the buffer, be sure to set the structures dwSize member to the appropriate value.

The returned DPN_APPLICATION_DESC structure will have the guidInstance, guidApplication, and pwszSessionName members set. It will not contain information about other clients that are connected to the session. That information, if available, can be obtained only from the server application. In particular, the dwCurrentPlayers member will always be set to 0.

To avoid accidentally overwriting the application description, applications should call IDirectPlay8Peer::GetApplicationDesc and fill in the DPN_APPLICATION_DESC structure before calling IDirectPlay8Peer::SetApplicationDesc.



© 2003 Microsoft Corporation. All rights reserved.