Export (0) Print
Expand All

IOleObject::GetUserType method

Retrieves the user-type name of an object for display in user-interface elements such as menus, list boxes, and dialog boxes.

Syntax


HRESULT GetUserType(
  [in]   DWORD dwFormOfType,
  [out]  LPOLESTR *pszUserType
);

Parameters

dwFormOfType [in]

The form of the user-type name to be presented to users. Possible values are obtained from the USERCLASSTYPE enumeration.

pszUserType [out]

Address of LPOLESTR pointer variable that receives a pointer to the user type string. The caller must free pszUserType using the current IMalloc instance. If an error occurs, the implementation must set pszUserType to NULL.

Return value

This method returns S_OK on success. Other possible return values include the following.

Return codeDescription
OLE_S_USEREG

Delegate to the default handler's implementation using the registry to provide the requested information.

 

Remarks

Containers call IOleObject::GetUserType in order to represent embedded objects in list boxes, menus, and dialog boxes by their normal, user-recognizable names. Examples include "Word Document," "Excel Chart," and "Paintbrush Object." The information returned by IOleObject::GetUserType is the user-readable equivalent of the binary class identifier returned by IOleObject::GetUserClassID.

Notes to Callers

The default handler's implementation of IOleObject::GetUserType uses the object's class identifier (the pClsid parameter returned by IOleObject::GetUserClassID) and the dwFormOfType parameter together as a key into the registry. If an entry is found that matches the key exactly, then the user type specified by that entry is returned. If only the CLSID part of the key matches, then the lowest-numbered entry available (usually the full name) is used. If the CLSID is not found, or there are no user types registered for the class, the user type currently found in the object's storage is used.

You should not cache the string returned from IOleObject::GetUserType. Instead, call this method each and every time the string is needed. This guarantees correct results when the embedded object is being converted from one type into another without the caller's knowledge. Calling this method is inexpensive because the default handler implements it using the registry.

Notes to Implementers

You can use the implementation provided by the default handler by returning OLE_S_USEREG as your application's implementation of this method. If the user type name is an empty string, the message "Unknown Object" is returned.

You can call the OLE helper function OleRegGetUserType to return the appropriate user type.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

OleIdl.h

IDL

OleIdl.Idl

IID

IID_IOleObject is defined as 00000112-0000-0000-C000-000000000046

See also

IOleObject
IOleObject::SetHostNames
IOleObject::GetUserClassID
OleRegGetUserType
ReadFmtUserTypeStg
USERCLASSTYPE

 

 

Community Additions

ADD
Show:
© 2014 Microsoft