IOleObject::GetUserType
A version of this page is also available for
4/8/2010
This 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(
DWORD dwFormOfType,
LPOLESTR* pszUserType
);
Parameters
dwFormOfType
[in] Specifies the form of the user-type name to be presented to users.Valid 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 IMalloccerefIMalloc instance.
If an error occurs, the implementation must set *pszUserType to NULL.
Return Value
One of the values in the following table is returned.
| Value | Description |
|---|---|
S_OK |
The object's user-type name is returned. |
OLE_S_USEREG |
Delegate to the default handler's implementation using the registry to provide the requested information. |
Remarks
Containers call GetUserType 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 GetUserType is the user-readable equivalent of the binary class identifier returned by IOleObject::GetUserClassID.
To determine whether the platform supports this interface, see Determining Supported COM APIs.
Notes to Callers
The default handler's implementation of GetUserType uses the object's class identifier (the pClsid parameter returned by GetUserClassID) and the dwFormOfType parameter together as a key into the registry.
If an entry is found that matches the key exactly, the user type specified by that entry is returned.
If only the CLSID part of the key matches, 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 found in the object's storage is used.
Do not cache the string returned from GetUserType. Instead, call this method 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.
Requirements
| Header | Oleidl.h, oleidl.idl |
| Library | oleaut32.lib, uuid.lib |
| Windows Embedded CE | Windows CE 2.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |
See Also
Reference
IOleObject
IMalloc
IOleObject::GetUserClassID