Amebis/atlex
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doxygen source annotation added

Browse Source
This commit is contained in:
Simon Rozman
2015-10-10 19:54:30 +02:00
parent 0ff5587137
commit 6dbd4151b7
8 changed files with 850 additions and 215 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
include/atlcrypt.h
View File

@@ -24,8 +24,18 @@
#include <atlstr.h>
#include <WinCrypt.h>
///
/// \defgroup ATLCryptoAPI Cryptography API
/// Integrates ATL classes with Microsoft Cryptography API
///
/// @{
inline DWORD CertGetNameStringA(PCCERT_CONTEXT pCertContext, DWORD dwType, DWORD dwFlags, void *pvTypePara, ATL::CAtlStringA &sNameString)
///
/// Obtains the subject or issuer name from a certificate [CERT_CONTEXT](https://msdn.microsoft.com/en-us/library/windows/desktop/aa377189.aspx) structure and stores it in a ATL::CAtlStringA string.
///
/// \sa [CertGetNameString function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376086.aspx)
///
inline DWORD CertGetNameStringA(_In_ PCCERT_CONTEXT pCertContext, _In_ DWORD dwType, _In_ DWORD dwFlags, _In_ void *pvTypePara, _Out_ ATL::CAtlStringA &sNameString)
{
// Query the final string length first.
DWORD dwSize = ::CertGetNameStringA(pCertContext, dwType, dwFlags, pvTypePara, NULL, 0);
@@ -39,7 +49,12 @@ inline DWORD CertGetNameStringA(PCCERT_CONTEXT pCertContext, DWORD dwType, DWORD
}
inline DWORD CertGetNameStringW(PCCERT_CONTEXT pCertContext, DWORD dwType, DWORD dwFlags, void *pvTypePara, ATL::CAtlStringW &sNameString)
///
/// Obtains the subject or issuer name from a certificate [CERT_CONTEXT](https://msdn.microsoft.com/en-us/library/windows/desktop/aa377189.aspx) structure and stores it in a ATL::CAtlStringW string.
///
/// \sa [CertGetNameString function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376086.aspx)
///
inline DWORD CertGetNameStringW(_In_ PCCERT_CONTEXT pCertContext, _In_ DWORD dwType, _In_ DWORD dwFlags, _In_ void *pvTypePara, _Out_ ATL::CAtlStringW &sNameString)
{
// Query the final string length first.
DWORD dwSize = ::CertGetNameStringW(pCertContext, dwType, dwFlags, pvTypePara, NULL, 0);
@@ -53,7 +68,12 @@ inline DWORD CertGetNameStringW(PCCERT_CONTEXT pCertContext, DWORD dwType, DWORD
}
inline BOOL CryptGetHashParam(__in HCRYPTHASH hHash, __in DWORD dwParam, __out ATL::CAtlArray<BYTE> &aData, __in DWORD dwFlags)
///
/// Retrieves data that governs the operations of a hash object. The actual hash value can be retrieved by using this function.
///
/// \sa [CryptGetHashParam function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379947.aspx)
///
inline BOOL CryptGetHashParam(_In_ HCRYPTHASH hHash, _In_ DWORD dwParam, _Out_ ATL::CAtlArray<BYTE> &aData, _In_ DWORD dwFlags)
{
DWORD dwHashSize;
@@ -74,7 +94,12 @@ inline BOOL CryptGetHashParam(__in HCRYPTHASH hHash, __in DWORD dwParam, __out
}
inline BOOL CryptExportKey(__in HCRYPTKEY hKey, __in HCRYPTKEY hExpKey, __in DWORD dwBlobType, __in DWORD dwFlags, __out ATL::CAtlArray<BYTE> &aData)
///
/// Exports a cryptographic key or a key pair from a cryptographic service provider (CSP) in a secure manner.
///
/// \sa [CryptExportKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379931.aspx)
///
inline BOOL CryptExportKey(_In_ HCRYPTKEY hKey, _In_ HCRYPTKEY hExpKey, _In_ DWORD dwBlobType, _In_ DWORD dwFlags, _Out_ ATL::CAtlArray<BYTE> &aData)
{
DWORD dwKeyBLOBSize;
@@ -94,24 +119,42 @@ inline BOOL CryptExportKey(__in HCRYPTKEY hKey, __in HCRYPTKEY hExpKey, __in DWO
return FALSE;
}
/// @}
namespace ATL
{
namespace Crypt
{
//
// CCertContext
//
/// \addtogroup ATLCryptoAPI
/// @{
///
/// PCCERT_CONTEXT wrapper class
///
class CCertContext : public ATL::CObjectWithHandleDuplT<PCCERT_CONTEXT>
{
public:
virtual ~CCertContext() throw()
///
/// Destroys the certificate context.
///
/// \sa [CertFreeCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376075.aspx)
///
virtual ~CCertContext()
{
if (m_h)
CertFreeCertificateContext(m_h);
}
inline BOOL Create(_In_ DWORD dwCertEncodingType, _In_ const BYTE *pbCertEncoded, _In_ DWORD cbCertEncoded) throw()
///
/// Creates the certificate context.
///
/// \return
/// - TRUE when creation succeeds;
/// - FALSE when creation fails. For extended error information, call `GetLastError()`.
/// \sa [CertCreateCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376033.aspx)
///
inline BOOL Create(_In_ DWORD dwCertEncodingType, _In_ const BYTE *pbCertEncoded, _In_ DWORD cbCertEncoded)
{
HANDLE h = CertCreateCertificateContext(dwCertEncodingType, pbCertEncoded, cbCertEncoded);
if (h) {
@@ -122,31 +165,56 @@ namespace ATL
}
protected:
///
/// Destroys the certificate context.
///
/// \sa [CertFreeCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376075.aspx)
///
virtual void InternalFree()
{
CertFreeCertificateContext(m_h);
}
virtual HANDLE InternalDuplicate(HANDLE h) const
///
/// Duplicates the certificate context.
///
/// \param[in] h Object handle of existing certificate context
/// \return Duplicated certificate context handle
/// \sa [CertDuplicateCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376045.aspx)
///
virtual HANDLE InternalDuplicate(_In_ HANDLE h) const
{
return CertDuplicateCertificateContext(h);
}
};
//
// CCertChainContext
//
///
/// PCCERT_CHAIN_CONTEXT wrapper class
///
class CCertChainContext : public ATL::CObjectWithHandleDuplT<PCCERT_CHAIN_CONTEXT>
{
public:
virtual ~CCertChainContext() throw()
///
/// Destroys the certificate chain context.
///
/// \sa [CertFreeCertificateChain function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376073.aspx)
///
virtual ~CCertChainContext()
{
if (m_h)
CertFreeCertificateChain(m_h);
}
inline BOOL Create(__in_opt HCERTCHAINENGINE hChainEngine, __in PCCERT_CONTEXT pCertContext, __in_opt LPFILETIME pTime, __in_opt HCERTSTORE hAdditionalStore, __in PCERT_CHAIN_PARA pChainPara, __in DWORD dwFlags, __reserved LPVOID pvReserved) throw()
///
/// Creates the certificate chain context.
///
/// \return
/// - TRUE when creation succeeds;
/// - FALSE when creation fails. For extended error information, call `GetLastError()`.
/// \sa [CertGetCertificateChain function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376078.aspx)
///
inline BOOL Create(_In_opt_ HCERTCHAINENGINE hChainEngine, _In_ PCCERT_CONTEXT pCertContext, _In_opt_ LPFILETIME pTime, _In_opt_ HCERTSTORE hAdditionalStore, _In_ PCERT_CHAIN_PARA pChainPara, _In_ DWORD dwFlags, __reserved LPVOID pvReserved)
{
HANDLE h;
if (CertGetCertificateChain(hChainEngine, pCertContext, pTime, hAdditionalStore, pChainPara, dwFlags, pvReserved, &h)) {
@@ -157,31 +225,56 @@ namespace ATL
}
protected:
///
/// Destroys the certificate chain context.
///
/// \sa [CertFreeCertificateChain function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376073.aspx)
///
virtual void InternalFree()
{
CertFreeCertificateChain(m_h);
}
virtual HANDLE InternalDuplicate(HANDLE h) const
///
/// Duplicates the certificate chain context.
///
/// \param[in] h Object handle of existing certificate chain context
/// \return Duplicated certificate chain context handle
/// \sa [CertDuplicateCertificateContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376045.aspx)
///
virtual HANDLE InternalDuplicate(_In_ HANDLE h) const
{
return CertDuplicateCertificateChain(h);
}
};
//
// CCertStore
//
///
/// HCERTSTORE wrapper class
///
class CCertStore : public ATL::CObjectWithHandleT<HCERTSTORE>
{
public:
virtual ~CCertStore() throw()
///
/// Closes the certificate store.
///
/// \sa [CertCloseStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376026.aspx)
///
virtual ~CCertStore()
{
if (m_h)
CertCloseStore(m_h, 0);
}
inline BOOL Create(__in LPCSTR lpszStoreProvider, __in DWORD dwEncodingType, __in_opt HCRYPTPROV_LEGACY hCryptProv, __in DWORD dwFlags, __in_opt const void *pvPara) throw()
///
/// Opens the certificate store.
///
/// \return
/// - TRUE when creation succeeds;
/// - FALSE when creation fails. For extended error information, call `GetLastError()`.
/// \sa [CertOpenStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376559.aspx)
///
inline BOOL Create(_In_ LPCSTR lpszStoreProvider, _In_ DWORD dwEncodingType, _In_opt_ HCRYPTPROV_LEGACY hCryptProv, _In_ DWORD dwFlags, _In_opt_ const void *pvPara)
{
HANDLE h = CertOpenStore(lpszStoreProvider, dwEncodingType, hCryptProv, dwFlags, pvPara);
if (h) {
@@ -192,6 +285,11 @@ namespace ATL
}
protected:
///
/// Closes the certificate store.
///
/// \sa [CertCloseStore function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa376026.aspx)
///
virtual void InternalFree()
{
CertCloseStore(m_h, 0);
@@ -199,19 +297,32 @@ namespace ATL
};
//
// CContext
//
///
/// HCRYPTPROV wrapper class
///
class CContext : public ATL::CObjectWithHandleT<HCRYPTPROV>
{
public:
virtual ~CContext() throw()
///
/// Releases the cryptographi context.
///
/// \sa [CryptReleaseContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380268.aspx)
///
virtual ~CContext()
{
if (m_h)
CryptReleaseContext(m_h, 0);
}
inline BOOL Create(__in_opt LPCTSTR szContainer, __in_opt LPCTSTR szProvider, __in DWORD dwProvType, __in DWORD dwFlags) throw()
///
/// Acquires the cryptographic context.
///
/// \return
/// - TRUE when creation succeeds;
/// - FALSE when creation fails. For extended error information, call `GetLastError()`.
/// \sa [CryptAcquireContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379886.aspx)
///
inline BOOL Create(_In_opt_ LPCTSTR szContainer, _In_opt_ LPCTSTR szProvider, _In_ DWORD dwProvType, _In_ DWORD dwFlags)
{
HANDLE h;
if (CryptAcquireContext(&h, szContainer, szProvider, dwProvType, dwFlags)) {
@@ -222,6 +333,11 @@ namespace ATL
}
protected:
///
/// Releases the cryptographic context.
///
/// \sa [CryptReleaseContext function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380268.aspx)
///
virtual void InternalFree()
{
CryptReleaseContext(m_h, 0);
@@ -229,19 +345,32 @@ namespace ATL
};
//
// CHash
//
class CHash : public ATL::CObjectWithHandleT<HCRYPTHASH>
///
/// HCRYPTHASH wrapper class
///
class CHash : public ATL::CObjectWithHandleDuplT<HCRYPTHASH>
{
public:
virtual ~CHash() throw()
///
/// Destroys the hash context.
///
/// \sa [CryptDestroyHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379917.aspx)
///
virtual ~CHash()
{
if (m_h)
CryptDestroyHash(m_h);
}
inline BOOL Create(__in HCRYPTPROV hProv, __in ALG_ID Algid, __in HCRYPTKEY hKey, __in DWORD dwFlags) throw()
///
/// Creates the hash context.
///
/// \return
/// - TRUE when creation succeeds;
/// - FALSE when creation fails. For extended error information, call `GetLastError()`.
/// \sa [CryptCreateHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379908.aspx)
///
inline BOOL Create(_In_ HCRYPTPROV hProv, _In_ ALG_ID Algid, _In_ HCRYPTKEY hKey, _In_ DWORD dwFlags)
{
HANDLE h;
if (CryptCreateHash(hProv, Algid, hKey, dwFlags, &h)) {
@@ -252,26 +381,54 @@ namespace ATL
}
protected:
///
/// Destroys the hash context.
///
/// \sa [CryptDestroyHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379917.aspx)
///
virtual void InternalFree()
{
CryptDestroyHash(m_h);
}
///
/// Duplicates the hash context.
///
/// \param[in] h Object handle of existing hash context
/// \return Duplicated hash context handle
/// \sa [CryptDuplicateHash function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379919.aspx)
///
virtual HANDLE InternalDuplicate(_In_ HANDLE h) const
{
HANDLE hNew = NULL;
return CryptDuplicateHash(h, NULL, 0, &hNew) ? hNew : NULL;
}
};
//
// CKey
//
class CKey : public ATL::CObjectWithHandleT<HCRYPTKEY>
///
/// HCRYPTKEY wrapper class
///
class CKey : public ATL::CObjectWithHandleDuplT<HCRYPTKEY>
{
public:
virtual ~CKey() throw()
///
/// Destroys the key.
///
/// \sa [CryptDestroyKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379918.aspx)
///
virtual ~CKey()
{
if (m_h)
CryptDestroyKey(m_h);
}
inline BOOL Generate(__in HCRYPTPROV hProv, __in ALG_ID Algid, __in DWORD dwFlags) throw()
///
/// Generates the key.
///
/// \sa [CryptGenKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379941.aspx)
///
inline BOOL Generate(_In_ HCRYPTPROV hProv, _In_ ALG_ID Algid, _In_ DWORD dwFlags)
{
HANDLE h;
if (CryptGenKey(hProv, Algid, dwFlags, &h)) {
@@ -281,7 +438,12 @@ namespace ATL
return FALSE;
}
inline BOOL Import(__in HCRYPTPROV hProv, __in_bcount(dwDataLen) CONST BYTE *pbData, __in DWORD dwDataLen, __in HCRYPTKEY hPubKey, __in DWORD dwFlags) throw()
///
/// Imports the key.
///
/// \sa [CryptImportKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380207.aspx)
///
inline BOOL Import(_In_ HCRYPTPROV hProv, __in_bcount(dwDataLen) CONST BYTE *pbData, _In_ DWORD dwDataLen, _In_ HCRYPTKEY hPubKey, _In_ DWORD dwFlags)
{
HANDLE h;
if (CryptImportKey(hProv, pbData, dwDataLen, hPubKey, dwFlags, &h)) {
@@ -291,7 +453,12 @@ namespace ATL
return FALSE;
}
inline BOOL ImportPublic(__in HCRYPTPROV hCryptProv, __in DWORD dwCertEncodingType, __in PCERT_PUBLIC_KEY_INFO pInfo) throw()
///
/// Imports the public key.
///
/// \sa [CryptImportPublicKeyInfo function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380209.aspx)
///
inline BOOL ImportPublic(_In_ HCRYPTPROV hCryptProv, _In_ DWORD dwCertEncodingType, _In_ PCERT_PUBLIC_KEY_INFO pInfo)
{
HANDLE h;
if (CryptImportPublicKeyInfo(hCryptProv, dwCertEncodingType, pInfo, &h)) {
@@ -302,10 +469,30 @@ namespace ATL
}
protected:
///
/// Destroys the key.
///
/// \sa [CryptDestroyKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379918.aspx)
///
virtual void InternalFree()
{
CryptDestroyKey(m_h);
}
///
/// Duplicates the key.
///
/// \param[in] h Object handle of existing key
/// \return Duplicated key handle
/// \sa [CryptDuplicateKey function](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379920.aspx)
///
virtual HANDLE InternalDuplicate(_In_ HANDLE h) const
{
HANDLE hNew = NULL;
return CryptDuplicateKey(h, NULL, 0, &hNew) ? hNew : NULL;
}
};
/// @}
}
}

17
include/atleap.h
View File

@@ -26,9 +26,21 @@ namespace ATL
{
namespace EAP
{
///
/// \defgroup ATLEAPAPI Extensible Authentication Protocol API
/// Integrates ATL classes with Microsoft EAP API
///
/// @{
///
/// EAP_ATTRIBUTE wrapper class
///
class CEAPAttribute : public EAP_ATTRIBUTE
{
public:
///
/// Initializes a new EAP attribute set to eatReserved.
///
CEAPAttribute()
{
eaType = eatReserved;
@@ -36,11 +48,16 @@ namespace ATL
pValue = NULL;
}
///
/// Destroys the EAP attribute.
///
~CEAPAttribute()
{
if (pValue)
delete pValue;
}
};
/// @}
}
}

497
include/atlex.h
View File

@@ -26,191 +26,213 @@
namespace ATL
{
/**
* Base abstract template class to support generic object handle keeping
* It provides basic operators and methods to ease the replacement of native object handle type with this template class and its descendands.
*/
///
/// \defgroup ATLSysHandles System Handles
/// Simplifies work with object handles of various type
///
/// @{
///
/// Base abstract template class to support generic object handle keeping
///
/// It provides basic operators and methods common to all descendands of this class establishing a base to ease the replacement of native object handle type with classes in object-oriented approach.
///
template <class T> class CObjectWithHandleT
{
public:
/**
* Datatype of the object handle this template class handles
*/
///
/// Datatype of the object handle this template class handles
///
typedef T HANDLE;
/**\name Constructors */
/**@{*/
/**
* The default constructor
* Sets the object handle to NULL.
*/
inline CObjectWithHandleT() throw() : m_h(NULL)
///
/// Initializes a new class instance with the object handle set to NULL.
///
inline CObjectWithHandleT() : m_h(NULL)
{
}
/**
*\param h Initial object handle value
*/
inline CObjectWithHandleT(_In_opt_ HANDLE h) throw() : m_h(h)
///
/// Initializes a new class instance with an available object handle.
///
/// \param[in] h Initial object handle value
///
inline CObjectWithHandleT(_In_opt_ HANDLE h) : m_h(h)
{
}
/**@}*/
/**\name Operators to allow transparent use of this class */
/**@{*/
/**
* Auto-typecasting operator
*\return Object handle
*/
inline operator HANDLE() const throw()
/// \name Operators for transparent usage of this class
/// @{
///
/// Auto-typecasting operator
///
/// \return Object handle
///
inline operator HANDLE() const
{
return m_h;
}
/**
* Operator to return object handle value when the object handle is a pointer to a value (class, struct, etc.)
*\return Object handle value
*/
///
/// Returns the object handle value when the object handle is a pointer to a value (class, struct, etc.).
///
/// \return Object handle value
///
inline HANDLE*& operator*() const
{
ATLENSURE(m_h != NULL);
return *m_h;
}
/**
* Operator to return object handle reference
*\return Object handle reference
*/
inline HANDLE* operator&() throw()
///
/// Returns the object handle reference.
/// \return Object handle reference
///
inline HANDLE* operator&()
{
ATLASSERT(m_h == NULL);
return &m_h;
}
/**
* Operator for object handle member access when the object handle is a pointer to a class or struct
*\return Object handle
*/
inline HANDLE operator->() const throw()
///
/// Provides object handle member access when the object handle is a pointer to a class or struct.
///
/// \return Object handle
///
inline HANDLE operator->() const
{
ATLASSERT(m_h != NULL);
return m_h;
}
/**@}*/
/**
* Test if the object handle is NULL
*\return
* - Non zero when object handle is NULL;
* - Zero otherwise.
*/
inline bool operator!() const throw()
/// @}
/// \name Comparison operators
/// @{
///
/// Tests if the object handle is NULL.
///
/// \return
/// - Non zero when object handle is NULL;
/// - Zero otherwise.
///
inline bool operator!() const
{
return m_h == NULL;
}
/**\name Comparison operators */
/**@{*/
/**
* Is less than
*\param h Object handle value to compare against
*\return
* - Non zero when object handle is less than h;
* - Zero otherwise.
*/
inline bool operator<(_In_opt_ HANDLE h) const throw()
///
/// Is handle less than?
///
/// \param[in] h Object handle to compare against
/// \return
/// - Non zero when object handle is less than h;
/// - Zero otherwise.
///
inline bool operator<(_In_opt_ HANDLE h) const
{
return m_h < h;
}
/**
* Is less than or equal to
*\param h Object handle value to compare against
*\return
* - Non zero when object handle is less than or equal to h;
* - Zero otherwise.
*/
inline bool operator<=(_In_opt_ HANDLE h) const throw()
///
/// Is handle less than or equal to?
///
/// \param[in] h Object handle to compare against
/// \return
/// - Non zero when object handle is less than or equal to h;
/// - Zero otherwise.
///
inline bool operator<=(_In_opt_ HANDLE h) const
{
return m_h <= h;
}
/**
* Is greater than or equal to
*\param h Object handle value to compare against
*\return
* - Non zero when object handle is greater than or equal to h;
* - Zero otherwise.
*/
inline bool operator>=(_In_opt_ HANDLE h) const throw()
///
/// Is handle greater than or equal to?
///
/// \param[in] h Object handle to compare against
/// \return
/// - Non zero when object handle is greater than or equal to h;
/// - Zero otherwise.
///
inline bool operator>=(_In_opt_ HANDLE h) const
{
return m_h >= h;
}
/**
* Is greater than
*\param h Object handle value to compare against
*\return
* - Non zero when object handle is greater than h;
* - Zero otherwise.
*/
inline bool operator>(_In_opt_ HANDLE h) const throw()
///
/// Is handle greater than?
///
/// \param[in] h Object handle to compare against
/// \return
/// - Non zero when object handle is greater than h;
/// - Zero otherwise.
///
inline bool operator>(_In_opt_ HANDLE h) const
{
return m_h > h;
}
/**
* Is not equal to
*\param h Object handle value to compare against
*\return
* - Non zero when object handle is not equal to h;
* - Zero otherwise.
*/
///
/// Is handle not equal to?
///
/// \param[in] h Object handle to compare against
/// \return
/// - Non zero when object handle is not equal to h;
/// - Zero otherwise.
///
inline bool operator!=(_In_opt_ HANDLE h) const
{
return !operator==(h);
}
/**
* Is equal to
*\param h Object handle value to compare against
*\return
* - Non zero when object handle is equal to h;
* - Zero otherwise.
*/
inline bool operator==(_In_opt_ HANDLE h) const throw()
///
/// Is handle equal to?
///
/// \param[in] h Object handle to compare against
/// \return
/// - Non zero when object handle is equal to h;
/// - Zero otherwise.
///
inline bool operator==(_In_opt_ HANDLE h) const
{
return m_h == h;
}
/**@}*/
/**
* Set a new object handle for the class
* When the current object handle of the class is non NULL, the object is destroyed first.
*\param h New object handle
*/
inline void Attach(_In_opt_ HANDLE h) throw()
/// @}
///
/// Sets a new object handle for the class
///
/// When the current object handle of the class is non-NULL, the object is destroyed first.
///
/// \param[in] h New object handle
///
inline void Attach(_In_opt_ HANDLE h)
{
if (m_h)
InternalFree();
m_h = h;
}
/**
* Dismiss the object handle from this class
*\return Object handle
*/
inline HANDLE Detach() throw()
///
/// Dismisses the object handle from this class
///
/// \return Object handle
///
inline HANDLE Detach()
{
HANDLE h = m_h;
m_h = NULL;
return h;
}
/**
* Destroys the object
*/
inline void Free() throw()
///
/// Destroys the object
///
inline void Free()
{
if (m_h) {
InternalFree();
@@ -218,31 +240,45 @@ namespace ATL
}
}
/// @}
protected:
/**
* Abstract method that must be implemented by child classes to do the actual object destruction
*/
///
/// Abstract member function that must be implemented by child classes to do the actual object destruction.
///
virtual void InternalFree() = 0;
protected:
/*** Object handle */
HANDLE m_h;
HANDLE m_h; ///< Object handle
};
//
// CObjectWithHandleDuplT
//
///
/// Base abstract template class to support object handle keeping for objects that support handle duplication
///
template <class T>
class CObjectWithHandleDuplT : public CObjectWithHandleT<T>
{
public:
///
/// Duplicates and returns a new object handle.
///
/// \return Duplicated object handle
///
inline HANDLE GetDuplicate() const
{
return m_h ? InternalDuplicate(m_h) : NULL;
}
inline BOOL DuplicateAndAttach(_In_opt_ HANDLE h) throw()
///
/// Duplicates an object handle and sets a new object handle.
///
/// \param[in] h Object handle of existing object
/// \return
/// - TRUE when duplication succeeds;
/// - FALSE when duplication fails. In case of failure obtaining the extended error information is object type specific (for example: `GetLastError()`).
///
inline BOOL DuplicateAndAttach(_In_opt_ HANDLE h)
{
if (m_h)
InternalFree();
@@ -268,18 +304,46 @@ namespace ATL
//}
protected:
virtual HANDLE InternalDuplicate(HANDLE h) const = 0;
///
/// Abstract member function that must be implemented by child classes to do the actual object handle duplication.
///
/// \param[in] h Object handle of existing object
/// \return Duplicated object handle
///
virtual HANDLE InternalDuplicate(_In_ HANDLE h) const = 0;
};
/// @}
//
// CStrFormatT, CStrFormatW, CStrFormatA, CStrFormat
//
///
/// \defgroup ATLStrFormat String Formatting
/// Formatted string generation
///
/// \par Example
/// \code
/// // Please note the PCSTR typecasting invokes an operator to return
/// // pointer to formatted buffer rather than class reference itself.
/// cout << (PCSTR)(CStrFormatA("%i is less than %i.\n", 1, 5));
/// \endcode
///
/// @{
///
/// Base template class to support string formatting using `printf()` style templates
///
template<typename BaseType, class StringTraits>
class CStrFormatT : public CStringT<BaseType, StringTraits>
{
public:
CStrFormatT(_In_z_ _FormatMessage_format_string_ PCXSTR pszFormat, ...)
/// \name Initializing string using template in memory
/// @{
///
/// Initializes a new string and formats its contents using `printf()` style template.
///
/// \param[in] pszFormat String template using `printf()` style
///
CStrFormatT(_In_z_ _Printf_format_string_ PCXSTR pszFormat, ...)
{
ATLASSERT(AtlIsValidString(pszFormat));
@@ -289,7 +353,17 @@ namespace ATL
va_end(argList);
}
CStrFormatT(_In_ _FormatMessage_format_string_ UINT nFormatID, ...)
/// @}
/// \name Initializing string using template in resources
/// @{
///
/// Initializes a new string and formats its contents using `printf()` style template in resources.
///
/// \param[in] nFormatID Resource ID of the string template using `printf()` style
///
CStrFormatT(_In_ UINT nFormatID, ...)
{
CStringT strFormat(GetManager());
ATLENSURE(strFormat.LoadString(nFormatID));
@@ -300,7 +374,13 @@ namespace ATL
va_end(argList);
}
CStrFormatT(_In_ HINSTANCE hInstance, _In_ _FormatMessage_format_string_ UINT nFormatID, ...)
///
/// Initializes a new string and formats its contents using `printf()` style template in resources.
///
/// \param[in] hInstance Resource module handle
/// \param[in] nFormatID Resource ID of the string template using `printf()` style
///
CStrFormatT(_In_ HINSTANCE hInstance, _In_ UINT nFormatID, ...)
{
CStringT strFormat(GetManager());
ATLENSURE(strFormat.LoadString(hInstance, nFormatID));
@@ -311,7 +391,14 @@ namespace ATL
va_end(argList);
}
CStrFormatT(_In_ HINSTANCE hInstance, _In_ WORD wLanguageID, _In_ _FormatMessage_format_string_ UINT nFormatID, ...)
///
/// Initializes a new string and formats its contents using `printf()` style template in resources.
///
/// \param[in] hInstance Resource module handle
/// \param[in] wLanguageID Resource language
/// \param[in] nFormatID Resource ID of the string template using `printf()` style
///
CStrFormatT(_In_ HINSTANCE hInstance, _In_ WORD wLanguageID, _In_ UINT nFormatID, ...)
{
CStringT strFormat(GetManager());
ATLENSURE(strFormat.LoadString(hInstance, nFormatID, wLanguageID));
@@ -321,20 +408,41 @@ namespace ATL
FormatV(strFormat, argList);
va_end(argList);
}
/// }@
};
///
/// Wide character implementation of a class to support string formatting using `printf()` style templates
///
typedef CStrFormatT< wchar_t, StrTraitATL< wchar_t, ChTraitsCRT< wchar_t > > > CStrFormatW;
///
/// Single-byte character implementation of a class to support string formatting using `printf()` style templates
///
typedef CStrFormatT< char, StrTraitATL< char, ChTraitsCRT< char > > > CStrFormatA;
///
/// TCHAR implementation of a class to support string formatting using `printf()` style templates
///
typedef CStrFormatT< TCHAR, StrTraitATL< TCHAR, ChTraitsCRT< TCHAR > > > CStrFormat;
//
// CStrFormatMsgT, CStrFormatMsgW, CStrFormatMsgA, CStrFormatMsg
//
///
/// Base template class to support string formatting using `FormatMessage()` style templates
///
template<typename BaseType, class StringTraits>
class CStrFormatMsgT : public CStringT<BaseType, StringTraits>
{
public:
/// \name Initializing string using template in memory
/// @{
///
/// Initializes a new string and formats its contents using `FormatMessage()` style template.
///
/// \param[in] pszFormat String template using `FormatMessage()` style
///
CStrFormatMsgT(_In_z_ _FormatMessage_format_string_ PCXSTR pszFormat, ...)
{
ATLASSERT(AtlIsValidString(pszFormat));
@@ -345,7 +453,17 @@ namespace ATL
va_end(argList);
}
CStrFormatMsgT(_In_ _FormatMessage_format_string_ UINT nFormatID, ...)
/// @}
/// \name Initializing string using template in resources
/// @{
///
/// Initializes a new string and formats its contents using `FormatMessage()` style template in resources.
///
/// \param[in] nFormatID Resource ID of the string template using `FormatMessage()` style
///
CStrFormatMsgT(_In_ UINT nFormatID, ...)
{
CStringT strFormat(GetManager());
ATLENSURE(strFormat.LoadString(nFormatID));
@@ -356,7 +474,13 @@ namespace ATL
va_end(argList);
}
CStrFormatMsgT(_In_ HINSTANCE hInstance, _In_ _FormatMessage_format_string_ UINT nFormatID, ...)
///
/// Initializes a new string and formats its contents using `FormatMessage()` style template in resources.
///
/// \param[in] hInstance Resource module handle
/// \param[in] nFormatID Resource ID of the string template using `FormatMessage()` style
///
CStrFormatMsgT(_In_ HINSTANCE hInstance, _In_ UINT nFormatID, ...)
{
CStringT strFormat(GetManager());
ATLENSURE(strFormat.LoadString(hInstance, nFormatID));
@@ -367,7 +491,14 @@ namespace ATL
va_end(argList);
}
CStrFormatMsgT(_In_ HINSTANCE hInstance, _In_ WORD wLanguageID, _In_ _FormatMessage_format_string_ UINT nFormatID, ...)
///
/// Initializes a new string and formats its contents using `FormatMessage()` style template in resources.
///
/// \param[in] hInstance Resource module handle
/// \param[in] wLanguageID Resource language
/// \param[in] nFormatID Resource ID of the string template using `FormatMessage()` style
///
CStrFormatMsgT(_In_ HINSTANCE hInstance, _In_ WORD wLanguageID, _In_ UINT nFormatID, ...)
{
CStringT strFormat(GetManager());
ATLENSURE(strFormat.LoadString(hInstance, nFormatID, wLanguageID));
@@ -377,32 +508,82 @@ namespace ATL
FormatMessageV(strFormat, &argList);
va_end(argList);
}
/// @}
};
///
/// Wide character implementation of a class to support string formatting using `FormatMessage()` style templates
///
typedef CStrFormatMsgT< wchar_t, StrTraitATL< wchar_t, ChTraitsCRT< wchar_t > > > CStrFormatMsgW;
///
/// Single-byte character implementation of a class to support string formatting using `FormatMessage()` style templates
///
typedef CStrFormatMsgT< char, StrTraitATL< char, ChTraitsCRT< char > > > CStrFormatMsgA;
///
/// TCHAR implementation of a class to support string formatting using `FormatMessage()` style templates
///
typedef CStrFormatMsgT< TCHAR, StrTraitATL< TCHAR, ChTraitsCRT< TCHAR > > > CStrFormatMsg;
/// @}
//
// CParanoidHeap
//
/// \defgroup ATLMemSanitize Auto-sanitize Memory Management
/// Sanitizes memory before dismissed
///
/// @{
///
/// A heap template that sanitizes each memory block before it is destroyed or reallocated
///
/// This template is typcally used to extend one of the base ATL heap management classes.
///
/// \par Example
/// \code
/// CParanoidHeap<CWin32Heap> myHeap;
/// \endcode
///
/// \note
/// CParanoidHeap introduces a performance penalty. However, it provides an additional level of security.
/// Use for security sensitive data memory storage only.
///
/// \sa [Memory Management Classes](https://msdn.microsoft.com/en-us/library/44yh1z4f.aspx)
///
template <class BaseHeap>
class CParanoidHeap : public BaseHeap {
public:
virtual void Free(_In_opt_ void* p) throw()
///
/// Sanitizes memory before freeing it
///
/// \param[in] p Pointer to heap memory block
///
virtual void Free(_In_opt_ void* p)
{
// Sanitize then free.
SecureZeroMemory(p, GetSize(p));
BaseHeap::Free(p);
}
_Ret_opt_bytecap_(nBytes) virtual void* Reallocate(_In_opt_ void* p, _In_ size_t nBytes) throw()
///
/// Safely reallocates the memory block by sanitizing memory at the previous location
///
/// This member function always performs the following steps (regardless of the current and new size):
/// 1. Allocates a new memory block,
/// 2. Copies the data,
/// 3. Sanitizes the old memory block,
/// 4. Frees the old memory block.
///
/// \param[in] p Pointer to heap memory block
/// \param[in] nBytes New size in bytes
/// \return Pointer to the new heap memory block
///
virtual /*_Ret_opt_bytecap_(nBytes)*/ void* Reallocate(_In_opt_ void* p, _In_ size_t nBytes)
{
// Create a new sized copy.
void *pNew = Allocate(nBytes);
size_t nSizePrev = GetSize(p);
memcpy(pNew, p, nSizePrev);
CopyMemory(pNew, p, nSizePrev);
// Sanitize the old data then free.
SecureZeroMemory(p, nSizePrev);
@@ -413,15 +594,31 @@ namespace ATL
};
//
// CW2AParanoidEX
//
///
/// Base template class to support string conversion with memory sanitization after use
///
template<int t_nBufferLength = 128>
class CW2AParanoidEX : public CW2AEX<t_nBufferLength> {
public:
///
/// Initializes a new class instance with the string provided.
///
/// \param[in] psz Pointer to wide string
///
CW2AParanoidEX(_In_z_ LPCWSTR psz) throw(...) : CW2AEX<t_nBufferLength>(psz) {}
///
/// Initializes a new class instance with the string provided.
///
/// \param[in] psz Pointer to wide string
/// \param[in] nCodePage Code page to use when converting to single-byte string
///
CW2AParanoidEX(_In_z_ LPCWSTR psz, _In_ UINT nCodePage) throw(...) : CW2AEX<t_nBufferLength>(psz, nCodePage) {}
~CW2AParanoidEX() throw()
///
/// Sanitizes string memory, then destroys it
///
~CW2AParanoidEX()
{
// Sanitize before free.
if (m_psz != m_szBuffer)
@@ -431,8 +628,10 @@ namespace ATL
}
};
//
// CW2AParanoid
//
///
/// Support for string conversion with memory sanitization after use
///
typedef CW2AParanoidEX<> CW2AParanoid;
/// @}
}

66
include/atlmsi.h
View File

@@ -23,8 +23,18 @@
#include <atlstr.h>
#include <MsiQuery.h>
///
/// \defgroup ATLMSIAPI Microsoft Installer API
/// Integrates ATL classes with Microsoft Installer API
///
/// @{
inline UINT MsiGetPropertyA(MSIHANDLE hInstall, LPCSTR szName, ATL::CAtlStringA &sValue)
///
/// Gets the value for an installer property and stores it in a ATL::CAtlStringA string.
///
/// \sa [MsiGetProperty function](https://msdn.microsoft.com/en-us/library/aa370134.aspx)
///
inline UINT MsiGetPropertyA(_In_ MSIHANDLE hInstall, _In_ LPCSTR szName, _Out_ ATL::CAtlStringA &sValue)
{
DWORD dwSize = 0;
UINT uiResult;
@@ -49,7 +59,12 @@ inline UINT MsiGetPropertyA(MSIHANDLE hInstall, LPCSTR szName, ATL::CAtlStringA
}
inline UINT MsiGetPropertyW(MSIHANDLE hInstall, LPCWSTR szName, ATL::CAtlStringW &sValue)
///
/// Gets the value for an installer property and stores it in a ATL::CAtlStringW string.
///
/// \sa [MsiGetProperty function](https://msdn.microsoft.com/en-us/library/aa370134.aspx)
///
inline UINT MsiGetPropertyW(_In_ MSIHANDLE hInstall, _In_ LPCWSTR szName, _Out_ ATL::CAtlStringW &sValue)
{
DWORD dwSize = 0;
UINT uiResult;
@@ -74,7 +89,12 @@ inline UINT MsiGetPropertyW(MSIHANDLE hInstall, LPCWSTR szName, ATL::CAtlStringW
}
inline UINT MsiRecordGetStringA(MSIHANDLE hRecord, unsigned int iField, ATL::CAtlStringA &sValue)
///
/// Returns the string value of a record field and stores it in a ATL::CAtlStringA string.
///
/// \sa [MsiRecordGetString function](https://msdn.microsoft.com/en-us/library/aa370368.aspx)
///
inline UINT MsiRecordGetStringA(_In_ MSIHANDLE hRecord, _In_ unsigned int iField, _Out_ ATL::CAtlStringA &sValue)
{
DWORD dwSize = 0;
UINT uiResult;
@@ -99,7 +119,12 @@ inline UINT MsiRecordGetStringA(MSIHANDLE hRecord, unsigned int iField, ATL::CAt
}
inline UINT MsiRecordGetStringW(MSIHANDLE hRecord, unsigned int iField, ATL::CAtlStringW &sValue)
///
/// Returns the string value of a record field and stores it in a ATL::CAtlStringW string.
///
/// \sa [MsiRecordGetString function](https://msdn.microsoft.com/en-us/library/aa370368.aspx)
///
inline UINT MsiRecordGetStringW(_In_ MSIHANDLE hRecord, _In_ unsigned int iField, _Out_ ATL::CAtlStringW &sValue)
{
DWORD dwSize = 0;
UINT uiResult;
@@ -124,6 +149,11 @@ inline UINT MsiRecordGetStringW(MSIHANDLE hRecord, unsigned int iField, ATL::CAt
}
///
/// Formats record field data and properties using a format string and stores it in a ATL::CAtlStringA string.
///
/// \sa [MsiFormatRecord function](https://msdn.microsoft.com/en-us/library/aa370109.aspx)
///
inline UINT MsiFormatRecordA(MSIHANDLE hInstall, MSIHANDLE hRecord, ATL::CAtlStringA &sValue)
{
DWORD dwSize = 0;
@@ -149,6 +179,11 @@ inline UINT MsiFormatRecordA(MSIHANDLE hInstall, MSIHANDLE hRecord, ATL::CAtlStr
}
///
/// Formats record field data and properties using a format string and stores it in a ATL::CAtlStringW string.
///
/// \sa [MsiFormatRecord function](https://msdn.microsoft.com/en-us/library/aa370109.aspx)
///
inline UINT MsiFormatRecordW(MSIHANDLE hInstall, MSIHANDLE hRecord, ATL::CAtlStringW &sValue)
{
DWORD dwSize = 0;
@@ -174,7 +209,12 @@ inline UINT MsiFormatRecordW(MSIHANDLE hInstall, MSIHANDLE hRecord, ATL::CAtlStr
}
inline UINT MsiRecordReadStream(MSIHANDLE hRecord, unsigned int iField, ATL::CAtlArray<BYTE> &binData)
///
/// Reads bytes from a record stream field into a ATL::CAtlArray<BYTE> buffer.
///
/// \sa [MsiRecordReadStream function](https://msdn.microsoft.com/en-us/library/aa370370.aspx)
///
inline UINT MsiRecordReadStream(_In_ MSIHANDLE hRecord, _In_ unsigned int iField, _Out_ ATL::CAtlArray<BYTE> &binData)
{
DWORD dwSize = 0;
UINT uiResult;
@@ -191,7 +231,12 @@ inline UINT MsiRecordReadStream(MSIHANDLE hRecord, unsigned int iField, ATL::CAt
}
inline UINT MsiGetTargetPathA(MSIHANDLE hInstall, LPCSTR szFolder, ATL::CAtlStringA &sValue)
///
/// Returns the full target path for a folder in the Directory table and stores it in a ATL::CAtlStringA string.
///
/// \sa [MsiGetTargetPath function](https://msdn.microsoft.com/en-us/library/aa370303.aspx)
///
inline UINT MsiGetTargetPathA(_In_ MSIHANDLE hInstall, _In_ LPCSTR szFolder, _Out_ ATL::CAtlStringA &sValue)
{
DWORD dwSize = 0;
UINT uiResult;
@@ -216,7 +261,12 @@ inline UINT MsiGetTargetPathA(MSIHANDLE hInstall, LPCSTR szFolder, ATL::CAtlStri
}
inline UINT MsiGetTargetPathW(MSIHANDLE hInstall, LPCWSTR szFolder, ATL::CAtlStringW &sValue)
///
/// Returns the full target path for a folder in the Directory table and stores it in a ATL::CAtlStringW string.
///
/// \sa [MsiGetTargetPath function](https://msdn.microsoft.com/en-us/library/aa370303.aspx)
///
inline UINT MsiGetTargetPathW(_In_ MSIHANDLE hInstall, _In_ LPCWSTR szFolder, _Out_ ATL::CAtlStringW &sValue)
{
DWORD dwSize = 0;
UINT uiResult;
@@ -239,3 +289,5 @@ inline UINT MsiGetTargetPathW(MSIHANDLE hInstall, LPCWSTR szFolder, ATL::CAtlStr
return uiResult;
}
}
/// @}

21
include/atlsec.h
View File

@@ -19,8 +19,18 @@
#include <Security.h>
///
/// \defgroup ATLSecurityAPI Security API
/// Integrates ATL classes with Microsoft Security API
///
/// @{
BOOLEAN GetUserNameExA(__in EXTENDED_NAME_FORMAT NameFormat, __out ATL::CAtlStringA &sName)
///
/// Retrieves the name of the user or other security principal associated with the calling thread and stores it in a ATL::CAtlStringA string.
///
/// \sa [GetUserNameEx function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724435.aspx)
///
BOOLEAN GetUserNameExA(_In_ EXTENDED_NAME_FORMAT NameFormat, _Out_ ATL::CAtlStringA &sName)
{
ULONG ulSize = 0;
@@ -52,7 +62,12 @@ BOOLEAN GetUserNameExA(__in EXTENDED_NAME_FORMAT NameFormat, __out ATL::CAtlStri
}
BOOLEAN GetUserNameExW(__in EXTENDED_NAME_FORMAT NameFormat, __out ATL::CAtlStringW &sName)
///
/// Retrieves the name of the user or other security principal associated with the calling thread and stores it in a ATL::CAtlStringW string.
///
/// \sa [GetUserNameEx function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724435.aspx)
///
BOOLEAN GetUserNameExW(_In_ EXTENDED_NAME_FORMAT NameFormat, _Out_ ATL::CAtlStringW &sName)
{
ULONG ulSize = 0;
@@ -82,3 +97,5 @@ BOOLEAN GetUserNameExW(__in EXTENDED_NAME_FORMAT NameFormat, __out ATL::CAtlStri
return NO_ERROR;
}
}
/// @}

17
include/atlshlwapi.h
View File

@@ -22,7 +22,17 @@
#include <atlstr.h>
#include <Shlwapi.h>
///
/// \defgroup ATLShellWAPI Shell API
/// Integrates ATL classes with Microsoft Shell API
///
/// @{
///
/// Simplifies a path by removing navigation elements such as "." and ".." to produce a direct, well-formed path, and stores it in a ATL::CAtlStringA string.
///
/// \sa [PathCanonicalize function](https://msdn.microsoft.com/en-us/library/windows/desktop/bb773569.aspx)
///
inline BOOL PathCanonicalizeA(__out ATL::CAtlStringA &sValue, __in LPCSTR pszPath)
{
// Prepare the buffer data and read into it.
@@ -38,6 +48,11 @@ inline BOOL PathCanonicalizeA(__out ATL::CAtlStringA &sValue, __in LPCSTR pszPat
}
///
/// Simplifies a path by removing navigation elements such as "." and ".." to produce a direct, well-formed path, and stores it in a ATL::CAtlStringW string.
///
/// \sa [PathCanonicalize function](https://msdn.microsoft.com/en-us/library/windows/desktop/bb773569.aspx)
///
inline BOOL PathCanonicalizeW(__out ATL::CAtlStringW &sValue, __in LPCWSTR pszPath)
{
// Prepare the buffer data and read into it.
@@ -51,3 +66,5 @@ inline BOOL PathCanonicalizeW(__out ATL::CAtlStringW &sValue, __in LPCWSTR pszPa
sValue.FreeExtra();
return bResult;
}
/// @}

166
include/atlwin.h
View File

@@ -24,8 +24,18 @@
#include <atlstr.h>
#include <Windows.h>
///
/// \defgroup ATLWinAPI Windows API
/// Integrates ATL classes with Microsoft Windows API
///
/// @{
inline DWORD GetModuleFileNameA(__in_opt HMODULE hModule, __out ATL::CAtlStringA &sValue)
///
/// Retrieves the fully qualified path for the file that contains the specified module and stores it in a ATL::CAtlStringA string.
///
/// \sa [GetModuleFileName function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms683197.aspx)
///
inline DWORD GetModuleFileNameA(_In_opt_ HMODULE hModule, _Out_ ATL::CAtlStringA &sValue)
{
DWORD dwSize = 0;
@@ -59,7 +69,12 @@ inline DWORD GetModuleFileNameA(__in_opt HMODULE hModule, __out ATL::CAtlStringA
}
inline DWORD GetModuleFileNameW(__in_opt HMODULE hModule, __out ATL::CAtlStringW &sValue)
///
/// Retrieves the fully qualified path for the file that contains the specified module and stores it in a ATL::CAtlStringW string.
///
/// \sa [GetModuleFileName function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms683197.aspx)
///
inline DWORD GetModuleFileNameW(_In_opt_ HMODULE hModule, _Out_ ATL::CAtlStringW &sValue)
{
DWORD dwSize = 0;
@@ -93,7 +108,12 @@ inline DWORD GetModuleFileNameW(__in_opt HMODULE hModule, __out ATL::CAtlStringW
}
inline int GetWindowTextA(__in HWND hWnd, __out ATL::CAtlStringA &sValue)
///
/// Copies the text of the specified window's title bar (if it has one) into a ATL::CAtlStringA string.
///
/// \sa [GetWindowText function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms633520.aspx)
///
inline int GetWindowTextA(_In_ HWND hWnd, _Out_ ATL::CAtlStringA &sValue)
{
int iResult;
@@ -117,7 +137,12 @@ inline int GetWindowTextA(__in HWND hWnd, __out ATL::CAtlStringA &sValue)
}
inline int GetWindowTextW(__in HWND hWnd, __out ATL::CAtlStringW &sValue)
///
/// Copies the text of the specified window's title bar (if it has one) into a ATL::CAtlStringW string.
///
/// \sa [GetWindowText function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms633520.aspx)
///
inline int GetWindowTextW(_In_ HWND hWnd, _Out_ ATL::CAtlStringW &sValue)
{
int iResult;
@@ -141,7 +166,12 @@ inline int GetWindowTextW(__in HWND hWnd, __out ATL::CAtlStringW &sValue)
}
inline BOOL GetFileVersionInfoA(__in LPCSTR lptstrFilename, __reserved DWORD dwHandle, __out ATL::CAtlArray<BYTE> &aValue)
///
/// Retrieves version information for the specified file and stores it in a ATL::CAtlStringA string.
///
/// \sa [GetFileVersionInfo function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms647003.aspx)
///
inline BOOL GetFileVersionInfoA(_In_ LPCSTR lptstrFilename, __reserved DWORD dwHandle, _Out_ ATL::CAtlArray<BYTE> &aValue)
{
// Get version info size.
DWORD dwVerInfoSize = ::GetFileVersionInfoSizeA(lptstrFilename, &dwHandle);
@@ -158,7 +188,12 @@ inline BOOL GetFileVersionInfoA(__in LPCSTR lptstrFilename, __reserved DWORD dwH
}
inline BOOL GetFileVersionInfoW(__in LPCWSTR lptstrFilename, __reserved DWORD dwHandle, __out ATL::CAtlArray<BYTE> &aValue)
///
/// Retrieves version information for the specified file and stores it in a ATL::CAtlStringW string.
///
/// \sa [GetFileVersionInfo function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms647003.aspx)
///
inline BOOL GetFileVersionInfoW(_In_ LPCWSTR lptstrFilename, __reserved DWORD dwHandle, _Out_ ATL::CAtlArray<BYTE> &aValue)
{
// Get version info size.
DWORD dwVerInfoSize = ::GetFileVersionInfoSizeW(lptstrFilename, &dwHandle);
@@ -175,7 +210,12 @@ inline BOOL GetFileVersionInfoW(__in LPCWSTR lptstrFilename, __reserved DWORD dw
}
inline DWORD ExpandEnvironmentStringsA(__in LPCSTR lpSrc, ATL::CAtlStringA &sValue)
///
/// Expands environment-variable strings, replaces them with the values defined for the current user, and stores it in a ATL::CAtlStringA string.
///
/// \sa [ExpandEnvironmentStrings function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724265.aspx)
///
inline DWORD ExpandEnvironmentStringsA(_In_ LPCSTR lpSrc, ATL::CAtlStringA &sValue)
{
DWORD dwBufferSizeEst = (DWORD)strlen(lpSrc) + 0x100; // Initial estimate
@@ -204,7 +244,12 @@ inline DWORD ExpandEnvironmentStringsA(__in LPCSTR lpSrc, ATL::CAtlStringA &sVal
}
inline DWORD ExpandEnvironmentStringsW(__in LPCWSTR lpSrc, ATL::CAtlStringW &sValue)
///
/// Expands environment-variable strings, replaces them with the values defined for the current user, and stores it in a ATL::CAtlStringW string.
///
/// \sa [ExpandEnvironmentStrings function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724265.aspx)
///
inline DWORD ExpandEnvironmentStringsW(_In_ LPCWSTR lpSrc, ATL::CAtlStringW &sValue)
{
DWORD dwBufferSizeEst = (DWORD)wcslen(lpSrc) + 0x100; // Initial estimate
@@ -233,7 +278,13 @@ inline DWORD ExpandEnvironmentStringsW(__in LPCWSTR lpSrc, ATL::CAtlStringW &sVa
}
inline VOID GuidToString(_In_ LPCGUID lpGuid, ATL::CAtlStringA &str)
///
/// Formats GUID and stores it in a ATL::CAtlStringA string.
///
/// \param[in] lpGuid Pointer to GUID
/// \param[out] str String to store the result to
///
inline VOID GuidToString(_In_ LPCGUID lpGuid, _Out_ ATL::CAtlStringA &str)
{
str.Format("{%08X-%04X-%04X-%02X%02X-%02X%02X%02X%02X%02X%02X}",
lpGuid->Data1,
@@ -244,7 +295,13 @@ inline VOID GuidToString(_In_ LPCGUID lpGuid, ATL::CAtlStringA &str)
}
inline VOID GuidToString(_In_ LPCGUID lpGuid, ATL::CAtlStringW &str)
///
/// Formats GUID and stores it in a ATL::CAtlStringW string.
///
/// \param[in] lpGuid Pointer to GUID
/// \param[out] str String to store the result to
///
inline VOID GuidToString(_In_ LPCGUID lpGuid, _Out_ ATL::CAtlStringW &str)
{
str.Format(L"{%08X-%04X-%04X-%02X%02X-%02X%02X%02X%02X%02X%02X}",
lpGuid->Data1,
@@ -255,6 +312,22 @@ inline VOID GuidToString(_In_ LPCGUID lpGuid, ATL::CAtlStringW &str)
}
///
/// Queries for a string value in the registry and stores it in a ATL::CAtlStringA string.
///
/// `REG_EXPAND_SZ` are expanded using `ExpandEnvironmentStrings()` before storing to sValue.
///
/// \param[in] hReg A handle to an open registry key. The key must have been opened with the KEY_QUERY_VALUE access right.
/// \param[in] pszName The name of the registry value. If lpValueName is NULL or an empty string, "", the function retrieves the type and data for the key's unnamed or default value, if any.
/// \param[out] sValue String to store the value to
/// \return
/// - `ERROR_SUCCESS` when query succeeds;
/// - `ERROR_INVALID_DATA` when the registy value type is not `REG_SZ`, `REG_MULTI_SZ`, or `REG_EXPAND_SZ`;
/// - `ERROR_OUTOFMEMORY` when the memory allocation for the sValue buffer fails;
/// - Error code when query fails. See `RegQueryValueEx()` for the list of error codes.
/// \sa [RegQueryValueEx function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724911.aspx)
/// \sa [ExpandEnvironmentStrings function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724265.aspx)
///
inline LSTATUS RegQueryStringValue(_In_ HKEY hReg, _In_z_ LPCSTR pszName, _Out_ ATL::CAtlStringA &sValue)
{
LSTATUS lResult;
@@ -288,6 +361,22 @@ inline LSTATUS RegQueryStringValue(_In_ HKEY hReg, _In_z_ LPCSTR pszName, _Out_
}
///
/// Queries for a string value in the registry and stores it in a ATL::CAtlStringW string.
///
/// `REG_EXPAND_SZ` are expanded using `ExpandEnvironmentStrings()` before storing to sValue.
///
/// \param[in] hReg A handle to an open registry key. The key must have been opened with the KEY_QUERY_VALUE access right.
/// \param[in] pszName The name of the registry value. If lpValueName is NULL or an empty string, "", the function retrieves the type and data for the key's unnamed or default value, if any.
/// \param[out] sValue String to store the value to
/// \return
/// - `ERROR_SUCCESS` when query succeeds;
/// - `ERROR_INVALID_DATA` when the registy value type is not `REG_SZ`, `REG_MULTI_SZ`, or `REG_EXPAND_SZ`;
/// - `ERROR_OUTOFMEMORY` when the memory allocation for the sValue buffer fails;
/// - Error code when query fails. See `RegQueryValueEx()` for the list of error codes.
/// \sa [RegQueryValueEx function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724911.aspx)
/// \sa [ExpandEnvironmentStrings function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724265.aspx)
///
inline LSTATUS RegQueryStringValue(_In_ HKEY hReg, _In_z_ LPCWSTR pszName, _Out_ ATL::CAtlStringW &sValue)
{
LSTATUS lResult;
@@ -321,7 +410,12 @@ inline LSTATUS RegQueryStringValue(_In_ HKEY hReg, _In_z_ LPCWSTR pszName, _Out_
}
inline LSTATUS RegQueryValueExA(__in HKEY hKey, __in_opt LPCSTR lpValueName, __reserved LPDWORD lpReserved, __out_opt LPDWORD lpType, __out ATL::CAtlArray<BYTE> &aData)
///
/// Retrieves the type and data for the specified value name associated with an open registry key and stores the data in a ATL::CAtlArray<BYTE> buffer.
///
/// \sa [RegQueryValueEx function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724911.aspx)
///
inline LSTATUS RegQueryValueExA(_In_ HKEY hKey, _In_opt_ LPCSTR lpValueName, __reserved LPDWORD lpReserved, _Out_opt_ LPDWORD lpType, _Out_ ATL::CAtlArray<BYTE> &aData)
{
LSTATUS lResult;
DWORD dwDataSize;
@@ -336,7 +430,12 @@ inline LSTATUS RegQueryValueExA(__in HKEY hKey, __in_opt LPCSTR lpValueName, __r
}
inline LSTATUS RegQueryValueExW(__in HKEY hKey, __in_opt LPCWSTR lpValueName, __reserved LPDWORD lpReserved, __out_opt LPDWORD lpType, __out ATL::CAtlArray<BYTE> &aData)
///
/// Retrieves the type and data for the specified value name associated with an open registry key and stores the data in a ATL::CAtlArray<BYTE> buffer.
///
/// \sa [RegQueryValueEx function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724911.aspx)
///
inline LSTATUS RegQueryValueExW(_In_ HKEY hKey, _In_opt_ LPCWSTR lpValueName, __reserved LPDWORD lpReserved, _Out_opt_ LPDWORD lpType, _Out_ ATL::CAtlArray<BYTE> &aData)
{
LSTATUS lResult;
DWORD dwDataSize;
@@ -353,7 +452,12 @@ inline LSTATUS RegQueryValueExW(__in HKEY hKey, __in_opt LPCWSTR lpValueName, __
#if _WIN32_WINNT >= _WIN32_WINNT_VISTA
inline LSTATUS RegLoadMUIStringA(__in HKEY hKey, __in_opt LPCSTR pszValue, __out ATL::CAtlStringA &sOut, __in DWORD Flags, __in_opt LPCSTR pszDirectory)
///
/// Loads the specified string from the specified key and subkey, and stores it in a ATL::CAtlStringA string.
///
/// \sa [RegLoadMUIString function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724890.aspx)
///
inline LSTATUS RegLoadMUIStringA(_In_ HKEY hKey, _In_opt_ LPCSTR pszValue, _Out_ ATL::CAtlStringA &sOut, _In_ DWORD Flags, _In_opt_ LPCSTR pszDirectory)
{
LSTATUS lResult;
DWORD dwSize;
@@ -372,7 +476,12 @@ inline LSTATUS RegLoadMUIStringA(__in HKEY hKey, __in_opt LPCSTR pszValue, __out
}
inline LSTATUS RegLoadMUIStringW(__in HKEY hKey, __in_opt LPCWSTR pszValue, __out ATL::CAtlStringW &sOut, __in DWORD Flags, __in_opt LPCWSTR pszDirectory)
///
/// Loads the specified string from the specified key and subkey, and stores it in a ATL::CAtlStringW string.
///
/// \sa [RegLoadMUIString function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms724890.aspx)
///
inline LSTATUS RegLoadMUIStringW(_In_ HKEY hKey, _In_opt_ LPCWSTR pszValue, _Out_ ATL::CAtlStringW &sOut, _In_ DWORD Flags, _In_opt_ LPCWSTR pszDirectory)
{
LSTATUS lResult;
DWORD dwSize;
@@ -392,19 +501,37 @@ inline LSTATUS RegLoadMUIStringW(__in HKEY hKey, __in_opt LPCWSTR pszValue, __ou
#endif
/// @}
namespace ATL
{
/// \addtogroup ATLWinAPI
/// @{
///
/// Module handle wrapper
///
class CAtlLibrary : public CObjectWithHandleT<HMODULE>
{
public:
virtual ~CAtlLibrary() throw()
///
/// Frees the module.
///
/// \sa [FreeLibrary](https://msdn.microsoft.com/en-us/library/windows/desktop/ms683152.aspx)
///
virtual ~CAtlLibrary()
{
if (m_h)
FreeLibrary(m_h);
}
inline BOOL Load(__in LPCTSTR lpFileName, __reserved HANDLE hFile, __in DWORD dwFlags) throw()
///
/// Loads the specified module into the address space of the calling process.
///
/// \sa [LoadLibraryEx](https://msdn.microsoft.com/en-us/library/windows/desktop/ms684179.aspx)
///
inline BOOL Load(_In_ LPCTSTR lpFileName, __reserved HANDLE hFile, _In_ DWORD dwFlags)
{
HANDLE h = LoadLibraryEx(lpFileName, hFile, dwFlags);
if (h) {
@@ -415,9 +542,16 @@ namespace ATL
}
protected:
///
/// Frees the module.
///
/// \sa [FreeLibrary](https://msdn.microsoft.com/en-us/library/windows/desktop/ms683152.aspx)
///
virtual void InternalFree()
{
FreeLibrary(m_h);
}
};
/// @}
}

14
include/atlwlan.h
View File

@@ -22,8 +22,18 @@
#include <atlstr.h>
#include <wlanapi.h>
///
/// \defgroup ATLWLANAPI WLAN API
/// Integrates ATL classes with Microsoft WLAN API
///
/// @{
inline DWORD WlanReasonCodeToString(__in DWORD dwReasonCode, __out ATL::CAtlStringW &sValue, __reserved PVOID pReserved)
///
/// Retrieves a string that describes a specified reason code and stores it in a ATL::CAtlStringW string.
///
/// \sa [WlanReasonCodeToString function](https://msdn.microsoft.com/en-us/library/windows/desktop/ms706768.aspx)
///
inline DWORD WlanReasonCodeToString(_In_ DWORD dwReasonCode, _Out_ ATL::CAtlStringW &sValue, __reserved PVOID pReserved)
{
DWORD dwSize = 0;
@@ -52,3 +62,5 @@ inline DWORD WlanReasonCodeToString(__in DWORD dwReasonCode, __out ATL::CAtlStri
}
}
}
/// @}