IDirectPlay8Peer::Host Method

Creates a new peer-to-peer 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 the device addresses that should be used to host the application. You must release these objects when you no longer need them.

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 NULL.

pdpCredentials

[in] Reserved. Must be NULL.

pvPlayerContext

[in] Pointer to the context value of the local 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_INVALIDDEVICEADDRESS	The address for the local computer or adapter is 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 IDirectPlay8Peer::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 IDirectPlay8Peer::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.