IDirectPlay8Client::Initialize Method

Registers an entry point in the client's code that receives the messages from the IDirectPlay8Client interface and from the server. This method must be called before calling any other methods of this interface.

Syntax

HRESULT Initialize(      

    PVOID const pvUserContext,
    const PFNDPNMESSAGEHANDLER pfn,
    const DWORD dwFlags
);

Parameters

pvUserContext

[in] Pointer to the user-provided context value in calls to the message handler. Providing a user-context value can be useful to differentiate messages coming from multiple interfaces to a common message handler.

pfn

[in] Pointer to a PFNDPNMESSAGEHANDLER callback function that receives all messages from the server, and receives indications of session changes from the IDirectPlay8Client interface.

dwFlags

[in] You can specify the following flags.

DPNINITIALIZE_DISABLEPARAMVAL

Disable parameter validation for the current object.

DPNINITIALIZE_HINT_LANSESSION

Opens a larger send window for games running on a local area network (LAN).

DPNINITIALIZE_DISABLELINKTUNING

Disable any attempts by Microsoft® DirectPlay® to tune the rate it sends at to the observed network conditions. Messages will be pushed out onto the network at the first available opportunity.

Return Value

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

DPNERR_INVALIDFLAGS	The flags passed to this method are invalid.
DPNERR_INVALIDPARAM	One or more of the parameters passed to the method are invalid.

Remarks

This is the first method you should call after using CoCreateInstance to obtain the IDirectPlay8Client interface.

Specify the DPNINITIALIZE_HINT_LANSESSION flag for sessions where all players will be on the same LAN.

Applications might want to specify the DPNINITIALIZE_DISABLELINKTUNING flag when they send at a fixed rate and do not alter the rate based on the network conditions. With this flag specified, DirectPlay will always assume the network has the capacity to carry all the application data and will therefore not attempt to tune its send rate to the network bandwidth. Specifying this flag and then sending at a rate that exceeds the capacity of the network will lead to unpredictable network behavior such as higher latency and increased packet drop rates. Applications that monitor the send queues and dynamically adjust their send rate to make best use of the available bandwidth should not specify this flag.

If the DPNINITIALIZE_DISABLELINKTUNING flag is specified, DirectPlay features such as message prioritization, coalescence, and timeout are not useful because messages always go directly to the network and are not queued.