IDirectPlay8Client::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 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_BUFFERTOOSMALL	The supplied buffer is not large enough to contain the requested data.
DPNERR_INVALIDFLAGS	The flags passed to this method are invalid.
DPNERR_INVALIDPARAM	One or more of the parameters passed to the method are invalid.
DPNERR_NOCONNECTION	No 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.