IDirectMusicObject8::SetDescriptor

DirectMusic

Microsoft DirectX 9.0 SDK Update (Summer 2004)

^{IDirectMusicObject8::SetDescriptor}

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

Syntax

HRESULT SetDescriptor(
  LPDMUS_OBJECTDESC pDesc
);

Parameters

pDesc

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

Return Values

If the method succeeds, one of the values in the following table is returned.

Return code	Description
S_OK	The descriptor was set.
S_FALSE	See Remarks.
DMUS_S_GARBAGE_COLLECTED	See Garbage Collection.

If it fails, the method can return one of the error values in the following table.

Return code

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 IDirectMusicObject8::GetDescriptor, the new description cannot successfully be passed to the IDirectMusicLoader8::GetObject method. For example, you could change the name of an object, but GetObject will 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

Header: Declared in dmusici.h.

See Also

previous page start next page