IDirectMusicObject::SetDescriptor

The IDirectMusicObject::SetDescriptor method sets some or all members of the object's internal description.

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 may return one of the following error values:

Remarks

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 alone.

This method is primarily used by the loader when creating an object. However, it can be used by an application to rename an object.

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.

If nothing else, an object should support DMUS_OBJ_NAME and DMUS_OBJ_OBJECT.

QuickInfo

  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