IDirectMusicObject::SetDescriptor

The IDirectMusicObject::SetDescriptor 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:

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, since 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

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dmusici.h.

See Also

IDirectMusicObject::ParseDescriptor, IDirectMusicObject::GetDescriptor