IDirectPlay8Server::Host Method

Creates a new client/server session, hosted by the local computer.

Syntax

HRESULT Host(      

    const DPN_APPLICATION_DESC *const pdnAppDesc,
    IDirectPlay8Address **const prgpDeviceInfo,
    const DWORD cDeviceInfo,
    const DPN_SECURITY_DESC *const pdpSecurity,
    const DPN_SECURITY_CREDENTIALS *const pdpCredentials,
    VOID *const pvPlayerContext,
    const DWORD dwFlags
);

Parameters

pdnAppDesc

[in] Pointer to a DPN_APPLICATION_DESC structure that describes the application.

prgpDeviceInfo

[in] Pointer to an array of IDirectPlay8Address objects containing device addresses that should be used to host the application.

cDeviceInfo

[in] Variable of type DWORD that specifies the number of device address objects in the array pointed to by prgpDeviceInfo.

pdpSecurity

[in] Reserved. Must be set to NULL.

pdpCredentials

[in] Reserved. Must be set to NULL.

pvPlayerContext

[in] Pointer to the context value of the player. This value is preset when the local computer handles the DPN_MSGID_CREATE_PLAYER message. This parameter is optional, and may be set to NULL.

dwFlags

[in] The following flag can be specified.

DPNHOST_OKTOQUERYFORADDRESSING

Setting this flag will display a standard Microsoft® DirectPlay® dialog box, which queries the user for more information if not enough information is passed in this method.

Return Value

Returns S_OK if successful, or the following error value.

DPNERR_DATATOOLARGE	The application data is too large for the service provider's Maximum Transmission Unit.
DPNERR_INVALIDPARAM	One or more of the parameters passed to the method are invalid.
DPNERR_DPNSVRNOTAVAILABLE	Port 6073 is already in use.
DPNERR_ALREADYINITIALIZED	The object has already been initialized.

Remarks

Do not set the guidInstance member of the DPN_APPLICATION_DESC structure when calling IDirectPlay8Server::Host because DirectPlay will ignore any value passed in and determine its own globally unique identifier (GUID). The only way to retrieve the guidInstance is by calling IDirectPlay8Server::GetApplicationDesc.

If you set the DPNHOST_OKTOQUERYFORADDRESSING flag in dwFlags, the service provider might attempt to display a dialog box to ask the user to complete the address information. You must have a visible window present when the service provider tries to display the dialog box, or your application will lock.

Data Value Summary specifies the required addressing information for each service provider.

The maximum size of the application data that you assign to the pvApplicationReservedData member of the DPN_APPLICATION_DESC structure is limited by the service provider's Maximum Transmission Unit. If your application data is too large, the method will fail and return DPNERR_DATATOOLARGE.