Edit

Share via

Registry and TypeLib Global Functions

  • Article

These functions provide support for loading and registering a type library.

Important

The functions listed in the following tables cannot be used in applications that execute in the Windows Runtime.

Name Description
AfxRegCreateKey Creates the specified registry key.
AfxRegDeleteKey Deletes the specified registry key.
AfxRegisterPreviewHandler A helper to register a preview handler.
AfxUnregisterPreviewHandler A helper to unregister a preview handler.
AtlRegisterTypeLib This function is called to register a type library.
AtlUnRegisterTypeLib This function is called to unregister a type library
AfxRegOpenKey Opens the specified registry key.
AfxRegOpenKeyEx Opens the specified registry key.
AtlLoadTypeLib This function is called to load a type library.
AtlUpdateRegistryFromResourceD This function is called to update the registry from the supplied resource.
RegistryDataExchange This function is called to read from, or write to, the system registry. Called by the Registry Data Exchange Macros.

These functions control which node in the registry the program uses to store information.

Name Description
AtlGetPerUserRegistration Retrieves whether the application redirects registry access to the HKEY_CURRENT_USER ( HKCU) node.
AtlSetPerUserRegistration Sets whether the application redirects registry access to the HKEY_CURRENT_USER ( HKCU) node.

Requirements

Header: atlbase.h

AtlGetPerUserRegistration

Use this function to determine whether the application redirects registry access to the HKEY_CURRENT_USER (HKCU) node.

Syntax

ATLINLINE ATLAPI AtlGetPerUserRegistration(bool* pEnabled);

Parameters

pEnabled
[out] TRUE indicates that the registry information is directed to the HKCU node; FALSE indicates that the application writes registry information to the default node. The default node is HKEY_CLASSES_ROOT (HKCR).

Return Value

S_OK if the method is successful, otherwise the HRESULT error code if an error occurs.

Remarks

Registry redirection is not enabled by default. If you enable this option, registry access is redirected to HKEY_CURRENT_USER\Software\Classes.

The redirection is not global. Only the MFC and ATL frameworks are affected by this registry redirection.

Requirements

Header: atlbase.h

AfxRegCreateKey

Creates the specified registry key.

Syntax

LONG AFXAPI AfxRegCreateKey(HKEY hKey, LPCTSTR lpSubKey, PHKEY phkResult, CAtlTransactionManager* pTM = NULL);

Parameters

hKey
A handle to an open registry key.

lpSubKey
The name of a key that this function opens or creates.

phkResult
A pointer to a variable that receives a handle to the opened or created key.

pTM
Pointer to a CAtlTransactionManager object.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in Winerror.h.

Requirements

Header: afxpriv.h

AfxRegDeleteKey

Deletes the specified registry key.

Syntax

LONG AFXAPI AfxRegDeleteKey(HKEY hKey, LPCTSTR lpSubKey, CAtlTransactionManager* pTM = NULL);

Parameters

hKey
A handle to an open registry key.

lpSubKey
The name of the key to be deleted.

pTM
Pointer to a CAtlTransactionManager object.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in Winerror.h.

Requirements

Header: afxpriv.h

A helper to register a preview handler.

Syntax

BOOL AFXAPI AfxRegisterPreviewHandler(LPCTSTR lpszCLSID, LPCTSTR lpszShortTypeName, LPCTSTR lpszFilterExt);

Parameters

lpszCLSID
Specifies the CLSID of handler.

lpszShortTypeName
Specifies the ProgID of handler.

lpszFilterExt
Specifies the file extension registered with this handler.

Requirements

Header: afxdisp.h

AtlRegisterTypeLib

This function is called to register a type library.

ATLAPI AtlRegisterTypeLib(HINSTANCE hInstTypeLib, LPCOLESTR lpszIndex);

Parameters

hInstTypeLib
The handle to the module instance.

lpszIndex
String in the format "\\N", where N is the integer index of the type library resource. Can be NULL if no index is required.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

This helper function is utilized by AtlComModuleUnregisterServer and CAtlComModule::RegisterTypeLib.

Requirements

Header: atlbase.h

AfxRegOpenKey

Opens the specified registry key.

Syntax

LONG AFXAPI AfxRegOpenKey(HKEY hKey, LPCTSTR lpSubKey, PHKEY phkResult, CAtlTransactionManager* pTM = NULL);

Parameters

hKey
A handle to an open registry key.

lpSubKey
The name of a key that this function opens or creates.

phkResult
A pointer to a variable that receives a handle to the created key.

pTM
Pointer to a CAtlTransactionManager object.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in Winerror.h.

Requirements

Header: afxpriv.h

AfxRegOpenKeyEx

Opens the specified registry key.

Syntax

LONG AFXAPI AfxRegOpenKeyEx(HKEY hKey, LPCTSTR lpSubKey, DWORD ulOptions, REGSAM samDesired, PHKEY phkResult, CAtlTransactionManager* pTM = NULL);

Parameters

hKey
A handle to an open registry key.

lpSubKey
The name of a key that this function opens or creates.

ulOptions
This parameter is reserved and must be zero.

samDesired
A mask that specifies the desired access rights to the key.

phkResult
A pointer to a variable that receives a handle to the opened key.

pTM
Pointer to a CAtlTransactionManager object.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in Winerror.h.

Requirements

Header: afxpriv.h

AfxUnregisterPreviewHandler

A helper to unregister a preview handler.

Syntax

BOOL AFXAPI AfxUnRegisterPreviewHandler(LPCTSTR lpszCLSID);

Parameters

lpszCLSID
Specifies the CLSID of the handler to be unregistered.

Requirements

Header: afxdisp.h

AtlSetPerUserRegistration

Sets whether the application redirects registry access to the HKEY_CURRENT_USER (HKCU) node.

Syntax

ATLINLINE ATLAPI AtlSetPerUserRegistration(bool bEnable);

Parameters

bEnable
[in] TRUE indicates that the registry information is directed to the HKCU node; FALSE indicates that the application writes registry information to the default node. The default node is HKEY_CLASSES_ROOT (HKCR).

Return Value

S_OK if the method is successful, otherwise the HRESULT error code if an error occurs.

Remarks

Registry redirection is not enabled by default. If you enable this option, registry access is redirected to HKEY_CURRENT_USER\Software\Classes.

The redirection is not global. Only the MFC and ATL frameworks are affected by this registry redirection.

Requirements

Header: atlbase.h

AtlUnRegisterTypeLib

This function is called to unregister a type library.

Syntax

ATLAPI AtlUnRegisterTypeLib(
    HINSTANCE hInstTypeLib,
    LPCOLESTR lpszIndex);

Parameters

hInstTypeLib
The handle to the module instance.

lpszIndex
String in the format "\\N", where N is the integer index of the type library resource. Can be NULL if no index is required.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

This helper function is utilized by CAtlComModule::UnRegisterTypeLib and AtlComModuleUnregisterServer.

Requirements

Header: atlbase.h

AtlLoadTypeLib

This function is called to load a type library.

Syntax

ATLINLINE ATLAPI AtlLoadTypeLib(
    HINSTANCE hInstTypeLib,
    LPCOLESTR lpszIndex,
    BSTR* pbstrPath,
    ITypeLib** ppTypeLib);

Parameters

hInstTypeLib
Handle to the module associated with the type library.

lpszIndex
String in the format "\\N", where N is the integer index of the type library resource. Can be NULL if no index is required.

pbstrPath
On successful return, contains the full path of the module associated with the type library.

ppTypeLib
On successful return, contains a pointer to a pointer to the loaded type library.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

This helper function is utilized by AtlRegisterTypeLib and AtlUnRegisterTypeLib.

AtlUpdateRegistryFromResourceD

This function was deprecated in Visual Studio 2013 and is removed in Visual Studio 2015.

<removed>

RegistryDataExchange

This function is called to read from, or write to, the system registry.

Syntax

HRESULT RegistryDataExchange(
    T* pT,
    enum RDXOperations rdxOp,
    void* pItem = NULL);

Parameters

pT
A pointer to the current object.

rdxOp
An enum value that indicates which operation the function should perform. See the table in the Remarks section for the allowed values.

pItem
Pointer to the data that is to be read from, or written to, the registry. The data can also represent a key to be deleted from the registry. The default value is NULL.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

The macros BEGIN_RDX_MAP and END_RDX_MAP expand to a function that calls RegistryDataExchange.

The possible enum values that indicate the operation the function should perform are shown in the following table:

Enum value Operation
eReadFromReg Read data from the registry.
eWriteToReg Write data to the registry.
eDeleteFromReg Delete the key from the registry.

Requirements

Header: atlbase.h

See also

Functions
Registry Data Exchange Macros