IDirectPlay8Address Interface

The IDirectPlay8Address interface contains generic addressing methods used to create and manipulate addresses for Microsoft?DirectPlay? This interface is one of the interfaces available through the CLSID_DirectPlay8Address Component Object Model (COM) object. To create an object that supports this interface, use the CoCreateInstanceEx method for the CLSID CLSID_DirectPlay8Address that specifies the IID_IDirectPlay8Address interface.

IDirectPlay8Address Members

AddComponent
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.
BuildFromDPADDRESS
Sets the current object's internal address to be the DirectPlay 8 equivalent of the specified DirectPlay 4 address. The purpose of this method is to allow lobby developers to launch games with the new DirectPlay interface using the old lobby code.
This method enumerates the address components in the specified address and adds the corresponding element to the DirectPlay 8 address.
BuildFromURLA
Sets the object equal to the specified DirectPlay ?URL string. It erases the contents of the object.
BuildFromURLW
Sets the object equal to the specified DirectPlay ?URL string. It erases the contents of the object.
Clear
Resets the address object to an empty address.
Duplicate
Creates a DirectPlay Address object that duplicates the address in this object.
GetComponentByIndex
Retrieves information about the component at the specified index. Values for the component are retrieved in their native format. If the component key is not found, the method returns DPNERR_DOESNOTEXIST.
The value of the component is retrieved in its native format. Therefore, if the component's value is a DWORD, a DWORD is retrieved by this call. So buffer size = 4 and pvBuffer should be a recast PDWORD.
GetComponentByName
Retrieves information about the component at the specified key. Values for the component are retrieved in their native format. If the component key is not found, DPNERR_DOESNOTEXIST is returned.
The value of the component is retrieved in its native format. Therefore, if the component's value is a DWORD, a DWORD is retrieved by this call. So buffer size = 4 and pvBuffer should be a recast PDWORD.
GetDevice
Retrieves the local device GUID in the address object. If no device is specified, this method returns DPNERR_DOESNOTEXIST.
GetNumComponents
Retrieves the number of components in the address.
GetSP
Retrieves the service provider GUID in the address object. If no service provider is specified, this method returns DPNERR_DOESNOTEXIST.
GetURLA Retrieves the DirectPlay address URL string represented by this object (ANSI version).
GetURLW
Retrieves the DirectPlay address URL string represented by this object.
GetUserData
Retrieves the user data in the address object. If no user data exists in this address object, this method returns DPNERR_DOESNOTEXIST.
IsEqual
Compares two addresses to see if they are equal.
SetDevice
Sets the local device GUID in the address object. If a local device is specified for this address, it is overwritten by this call.
SetEqual
Sets the contents of the object it is called on to match the contents of the address object passed to the method.
SetSP
Sets the service provider GUID in the address object. If a service provider is specified for this address, it is overwritten by this call.
SetUserData
Sets the user data in the address object. If there is user data in this address, it is overwritten by this call.

Remarks

In order to deliver messages, each participant in a multiplayer game must have a unique address. Addresses can refer either to the computer that your application is running on (device address), or a computer that your application needs to communicate with (host address).
DirectPlay represents addresses as URLs. These URLs are then encapsulated in the address object so that they can be passed to or from the DirectPlay API. In general, address URLs are strings that consist of three basic components in the following order: scheme, scheme separator, and data string.
All DirectPlay addresses use "x-directplay" as the scheme, and ":/" as the scheme separator. Using ":/" as a separator implies that the data that follows is opaque. In other words, the data string does not conform to any Internet standard, and should just be passed on to the receiving application without modification. All DirectPlay URLs thus have the following general form:
x-directplay:/[data string]
There are two basic approaches to handling address objects:
Handle the data string directly, using normal string manipulation techniques.
Use the methods exposed by IDirectPlay8Address to obtain or modify the individual elements of the data string.
For more information about DirectPlay addresses, see DirectPlay Addressing.

Interface Information

Inherits from IUnknown
Header dpaddr.h
Minimum operating systems Windows 98, Pocket PC 2002

AddComponent	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.
BuildFromDPADDRESS	Sets the current object's internal address to be the DirectPlay 8 equivalent of the specified DirectPlay 4 address. The purpose of this method is to allow lobby developers to launch games with the new DirectPlay interface using the old lobby code. This method enumerates the address components in the specified address and adds the corresponding element to the DirectPlay 8 address.
BuildFromURLA	Sets the object equal to the specified DirectPlay ?URL string. It erases the contents of the object.
BuildFromURLW	Sets the object equal to the specified DirectPlay ?URL string. It erases the contents of the object.
Clear	Resets the address object to an empty address.
Duplicate	Creates a DirectPlay Address object that duplicates the address in this object.
GetComponentByIndex	Retrieves information about the component at the specified index. Values for the component are retrieved in their native format. If the component key is not found, the method returns DPNERR_DOESNOTEXIST. The value of the component is retrieved in its native format. Therefore, if the component's value is a DWORD, a DWORD is retrieved by this call. So buffer size = 4 and pvBuffer should be a recast PDWORD.
GetComponentByName	Retrieves information about the component at the specified key. Values for the component are retrieved in their native format. If the component key is not found, DPNERR_DOESNOTEXIST is returned. The value of the component is retrieved in its native format. Therefore, if the component's value is a DWORD, a DWORD is retrieved by this call. So buffer size = 4 and pvBuffer should be a recast PDWORD.
GetDevice	Retrieves the local device GUID in the address object. If no device is specified, this method returns DPNERR_DOESNOTEXIST.
GetNumComponents	Retrieves the number of components in the address.
GetSP	Retrieves the service provider GUID in the address object. If no service provider is specified, this method returns DPNERR_DOESNOTEXIST.
GetURLA	Retrieves the DirectPlay address URL string represented by this object (ANSI version).
GetURLW	Retrieves the DirectPlay address URL string represented by this object.
GetUserData	Retrieves the user data in the address object. If no user data exists in this address object, this method returns DPNERR_DOESNOTEXIST.
IsEqual	Compares two addresses to see if they are equal.
SetDevice	Sets the local device GUID in the address object. If a local device is specified for this address, it is overwritten by this call.
SetEqual	Sets the contents of the object it is called on to match the contents of the address object passed to the method.
SetSP	Sets the service provider GUID in the address object. If a service provider is specified for this address, it is overwritten by this call.
SetUserData	Sets the user data in the address object. If there is user data in this address, it is overwritten by this call.

Inherits from	IUnknown
Header	dpaddr.h
Minimum operating systems	Windows 98, Pocket PC 2002