IDirectPlay8Address Interface

DirectPlay

 
Microsoft DirectX 9.0 SDK Update (Summer 2003)

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 fromIUnknown
Headerdpaddr.h
Minimum operating systems Windows 98, Pocket PC 2002

© 2003 Microsoft Corporation. All rights reserved.