IDirectPlay8Address::AddComponent Method

Adds a component to the address. If the component is part of the address, it is replaced by the new value in this call.

Values are specified in native formats when making this call. Therefore, the lpvData parameter should be a recast pointer to a variable that holds the data in the native format. For example, if the component is a globally unique identifier (GUID), the lpvData parameter should be a recast pointer to a GUID.

This method validates that the predefined component types are the right format.

Syntax

HRESULT AddComponent(      
    const WCHAR *const pwszName,
    const void *const lpvData,
    const DWORD dwDataSize,
    const DWORD dwDataType
);

Parameters

pwszName

[in] NULL-terminated Unicode string that contains the key for the component. You can set this to a valid string or use one of the following predefined values.

DPNA_KEY_APPLICATION_INSTANCE

DPNA_KEY_BAUD

DPNA_KEY_DEVICE

DPNA_KEY_FLOWCONTROL

DPNA_KEY_HOSTNAME

DPNA_KEY_NAMEINFO

DPNA_KEY_NAT_RESOLVER

DPNA_KEY_NAT_RESOLVER_USER_STRING

DPNA_KEY_PARITY

DPNA_KEY_PHONENUMBER

DPNA_KEY_PORT

DPNA_KEY_PROCESSOR

DPNA_KEY_PROGRAM

DPNA_KEY_PROVIDER

DPNA_KEY_SCOPE

DPNA_KEY_STOPBITS

DPNA_KEY_TRAVERSALMODE

lpvData

[in] Pointer to a buffer that contains the value associated with the specified key. Data should be specified in its native format.

dwDataSize

[in] Size, in bytes, of the data in the buffer located at lpvData. The size depends on the data type. If the size is not specified correctly, the method returns DPNERR_INVALIDPARAM.

DWORD

Size = sizeof( DWORD )

GUID

Size = sizeof( GUID )

String

Size = size of the string in bytes, including the terminating NULL character.

dwDataType

[in] Data type of the value associated with this key. The data type can be one of the following:

DPNA_DATATYPE_STRING

Data is a NULL-terminated string.

DPNA_DATATYPE_STRING_ANSI

Data is a NULL-terminated ANSI string.

DPNA_DATATYPE_DWORD

Data is a DWORD.

DPNA_DATATYPE_GUID

Data is a GUID.

DPNA_DATATYPE_BINARY

Data is in raw binary format.

Return Value

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

DPNERR_INVALIDPARAM	One or more of the parameters passed to the method are invalid.
DPNERR_INVALIDPOINTER	Pointer specified as a parameter is invalid.
DPNERR_NOTALLOWED	This function is not allowed on this object.

Remarks

For a discussion of various address components and their keys, see Data Values.