Registry and TypeLib Global Functions
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
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for