IDirectMusicObject::SetDescriptor

  • Article

This method sets some or all members of the object's internal description.

This method is primarily used by the loader when creating an object, and is not normally used directly by an application. However, if an application implements an object type in DirectMusic, it should support this method.

HRESULT SetDescriptor(
  LPDMUS_OBJECTDESC pDesc
);

Parameters

  • pDesc
    Address of a DMUS_OBJECTDESC structure to receive data about the object. Data is copied to all members that are enabled in the dwValidData member

Return Values

If the method succeeds, the return value is S_OK, or S_FALSE (see Remarks).

If it fails, the method can return one of the following error values:

E_INVALIDARG
E_POINTER

Remarks

Applications do not normally call this method on standard objects. Although it is possible to change the object descriptor returned by IDirectMusicObject::GetDescriptor, the new description cannot successfully be passed to the IDirectMusicLoader::GetObject method. For example, you could change the name of an object, but GetObject still find the object only under its original name, because it relies on the object's own implementation of SetDescriptor.

Members that are not copied keep their previous values. For example, an object might already have its name and GUID stored internally. A call to its SetDescriptor method with a new name and file path (and DMUS_OBJ_NAME | DMUS_OBJ_FILENAME in the dwValidData member) would replace the name, supply a file name, and leave the GUID as it is.

If the object is unable to set one or more members, it sets the members that it does support, clears the flags in dwValidData that it does not support, and returns S_FALSE. An application-defined object should support at least DMUS_OBJ_NAME and DMUS_OBJ_OBJECT.

Requirements

OS Versions: Windows CE .NET 4.0 and Windows CE .NET 4.1.
Header: Dmusici.h.
Link Library: Dmusic.lib.

See Also

IDirectMusicLoader::GetObject | IDirectMusicObject::GetDescriptor | IDirectMusicObject::ParseDescriptor | DMUS_OBJECTDESC

 Last updated on Monday, April 12, 2004

© 1992-2002 Microsoft Corporation. All rights reserved.