IDirectPlay8Server::Initialize Method

Registers an entry point in the server's code that receives the messages from the IDirectPlay8Server interface and from remote clients. 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 is useful to differentiate messages from multiple interfaces to a common message handler.

pfn

[in] Pointer to a PFNDPNMESSAGEHANDLER callback function that receives all messages from remote clients and indications of session changes from the IDirectPlay8Server interface.

dwFlags

[in] You can specify the following flags.

DPNINITIALIZE_DISABLEPARAMVAL

Passing this flag will 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

Call this method first after using CoCreateInstance to obtain the IDirectPlay8Server interface.

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.