From 250c7c08bbd540421d7bbb4976ab6958b3526a2b Mon Sep 17 00:00:00 2001 From: James Hawkins Date: Mon, 12 Jul 2004 23:32:10 +0000 Subject: [PATCH] Added some more API docs. --- dlls/advapi32/advapi.c | 25 ++- dlls/advapi32/crypt.c | 421 ++++++++++++++++++++++++++++++++++++++- dlls/advapi32/eventlog.c | 188 +++++++++++++---- 3 files changed, 587 insertions(+), 47 deletions(-) diff --git a/dlls/advapi32/advapi.c b/dlls/advapi32/advapi.c index f6a922b4754..a97b09f0435 100644 --- a/dlls/advapi32/advapi.c +++ b/dlls/advapi32/advapi.c @@ -155,6 +155,27 @@ BOOL WINAPI AbortSystemShutdownW( LPWSTR lpMachineName ) /****************************************************************************** * InitiateSystemShutdownExA [ADVAPI32.@] + * + * Initiate a shutdown or optionally restart the computer. + * + * PARAMS + * lpMachineName [I] Network name of machine to shutdown. + * lpMessage [I] Message displayed in shutdown dialog box. + * dwTimeout [I] Number of seconds dialog is displayed before shutdown. + * bForceAppsClosed [I] If TRUE, apps close without saving, else dialog is + * displayed requesting user to close apps. + * bRebootAfterShutdown [I] If TRUE, system reboots after restart, else the + * system flushes all caches to disk and clears + * the screen + * dwReason [I] Reason for shutting down. Must be a system shutdown reason + * code. + * + * RETURNS + * Success: TRUE + * Failure: FALSE + * + * NOTES + * if lpMachineName is NULL, the local computer is shutdown. */ BOOL WINAPI InitiateSystemShutdownExA( LPSTR lpMachineName, LPSTR lpMessage, DWORD dwTimeout, BOOL bForceAppsClosed, BOOL bRebootAfterShutdown, @@ -167,7 +188,9 @@ BOOL WINAPI InitiateSystemShutdownExA( LPSTR lpMachineName, LPSTR lpMessage, } /****************************************************************************** - * InitiateSystemShutdownExA [ADVAPI32.@] + * InitiateSystemShutdownExW [ADVAPI32.@] + * + * see InitiateSystemShutdownExA */ BOOL WINAPI InitiateSystemShutdownExW( LPWSTR lpMachineName, LPWSTR lpMessage, DWORD dwTimeout, BOOL bForceAppsClosed, BOOL bRebootAfterShutdown, diff --git a/dlls/advapi32/crypt.c b/dlls/advapi32/crypt.c index e2db49a300b..4d02ff439c4 100644 --- a/dlls/advapi32/crypt.c +++ b/dlls/advapi32/crypt.c @@ -478,6 +478,8 @@ error: /****************************************************************************** * CryptAcquireContextW (ADVAPI32.@) + * + * see CryptAcquireContextA */ BOOL WINAPI CryptAcquireContextW (HCRYPTPROV *phProv, LPCWSTR pszContainer, LPCWSTR pszProvider, DWORD dwProvType, DWORD dwFlags) @@ -508,6 +510,18 @@ BOOL WINAPI CryptAcquireContextW (HCRYPTPROV *phProv, LPCWSTR pszContainer, /****************************************************************************** * CryptContextAddRef (ADVAPI32.@) + * + * Increases reference count of a cryptographic service provider handle + * by one. + * + * PARAMS + * hProv [I] Handle to the CSP whose reference is being incremented. + * pdwReserved [IN] Reserved for future use and must be NULL. + * dwFlags [I] Reserved for future use and must be NULL. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptContextAddRef (HCRYPTPROV hProv, DWORD *pdwReserved, DWORD dwFlags) { @@ -518,6 +532,16 @@ BOOL WINAPI CryptContextAddRef (HCRYPTPROV hProv, DWORD *pdwReserved, DWORD dwFl /****************************************************************************** * CryptReleaseContext (ADVAPI32.@) + * + * Releases the handle of a CSP. Reference count is decreased. + * + * PARAMS + * hProv [I] Handle of a CSP. + * dwFlags [I] Reserved for future use and must be NULL. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptReleaseContext (HCRYPTPROV hProv, DWORD dwFlags) { @@ -546,6 +570,20 @@ BOOL WINAPI CryptReleaseContext (HCRYPTPROV hProv, DWORD dwFlags) /****************************************************************************** * CryptGenRandom (ADVAPI32.@) + * + * Fills a buffer with cryptographically random bytes. + * + * PARAMS + * hProv [I] Handle of a CSP. + * dwLen [I] Number of bytes to generate. + * pbBuffer [I/O] Buffer to contain random bytes. + * + * RETURNS + * Success: TRUE + * Failure: FALSE + * + * NOTES + * pdBuffer must be at least dwLen bytes long. */ BOOL WINAPI CryptGenRandom (HCRYPTPROV hProv, DWORD dwLen, BYTE *pbBuffer) { @@ -561,6 +599,22 @@ BOOL WINAPI CryptGenRandom (HCRYPTPROV hProv, DWORD dwLen, BYTE *pbBuffer) /****************************************************************************** * CryptCreateHash (ADVAPI32.@) + * + * Initiates the hashing of a stream of data. + * + * PARAMS + * hProv [I] Handle of a CSP. + * Algid [I] Identifies the hash algorithm to use. + * hKey [I] Key for the hash (if required). + * dwFlags [I] Reserved for future use and must be NULL. + * phHash [O] Address of the future handle to the new hash object. + * + * RETURNS + * Success: TRUE + * Failure: FALSE + * + * NOTES + * If the algorithm is a keyed hash, hKey is the key. */ BOOL WINAPI CryptCreateHash (HCRYPTPROV hProv, ALG_ID Algid, HCRYPTKEY hKey, DWORD dwFlags, HCRYPTHASH *phHash) @@ -596,6 +650,21 @@ BOOL WINAPI CryptCreateHash (HCRYPTPROV hProv, ALG_ID Algid, HCRYPTKEY hKey, /****************************************************************************** * CryptDecrypt (ADVAPI32.@) + * + * Decrypts data encrypted by CryptEncrypt. + * + * PARAMS + * hKey [I] Handle to the decryption key. + * hHash [I] Handle to a hash object. + * Final [I] TRUE if this is the last section to be decrypted. + * dwFlags [I] Reserved for future use. Can be CRYPT_OAEP. + * pbData [I/O] Buffer that holds the encrypted data. Holds decrypted + * data on return + * pdwDataLen [I/O] Length of pbData before and after the call. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptDecrypt (HCRYPTKEY hKey, HCRYPTHASH hHash, BOOL Final, DWORD dwFlags, BYTE *pbData, DWORD *pdwDataLen) @@ -616,6 +685,19 @@ BOOL WINAPI CryptDecrypt (HCRYPTKEY hKey, HCRYPTHASH hHash, BOOL Final, /****************************************************************************** * CryptDeriveKey (ADVAPI32.@) + * + * Generates session keys derived from a base data value. + * + * PARAMS + * hProv [I] Handle to a CSP. + * Algid [I] Identifies the symmetric encryption algorithm to use. + * hBaseData [I] Handle to a hash object. + * dwFlags [I] Type of key to generate. + * phKey [I/O] Address of the newly generated key. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptDeriveKey (HCRYPTPROV hProv, ALG_ID Algid, HCRYPTHASH hBaseData, DWORD dwFlags, HCRYPTKEY *phKey) @@ -647,6 +729,15 @@ BOOL WINAPI CryptDeriveKey (HCRYPTPROV hProv, ALG_ID Algid, HCRYPTHASH hBaseData /****************************************************************************** * CryptDestroyHash (ADVAPI32.@) + * + * Destroys the hash object referenced by hHash. + * + * PARAMS + * hHash [I] Handle of the hash object to be destroyed. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptDestroyHash (HCRYPTHASH hHash) { @@ -666,7 +757,16 @@ BOOL WINAPI CryptDestroyHash (HCRYPTHASH hHash) } /****************************************************************************** - * CryptDestroyKey (ADVAPI32.@) + * CryptDestroyKey (ADVAPI32.@) + * + * Releases the handle referenced by hKey. + * + * PARAMS + * hKey [I] Handle of the key to be destroyed. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptDestroyKey (HCRYPTKEY hKey) { @@ -687,6 +787,18 @@ BOOL WINAPI CryptDestroyKey (HCRYPTKEY hKey) /****************************************************************************** * CryptDuplicateHash (ADVAPI32.@) + * + * Duplicates a hash. + * + * PARAMS + * hHash [I] Handle to the hash to be copied. + * pdwReserved [I] Reserved for future use and must be zero. + * dwFlags [I] Reserved for future use and must be zero. + * phHash [O] Address of the handle to receive the copy. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptDuplicateHash (HCRYPTHASH hHash, DWORD *pdwReserved, DWORD dwFlags, HCRYPTHASH *phHash) @@ -719,6 +831,18 @@ BOOL WINAPI CryptDuplicateHash (HCRYPTHASH hHash, DWORD *pdwReserved, /****************************************************************************** * CryptDuplicateKey (ADVAPI32.@) + * + * Duplicate a key and the key's state. + * + * PARAMS + * hKey [I] Handle of the key to copy. + * pdwReserved [I] Reserved for future use and must be NULL. + * dwFlags [I] Reserved for future use and must be zero. + * phKey [I] Address of the handle to the duplicated key. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptDuplicateKey (HCRYPTKEY hKey, DWORD *pdwReserved, DWORD dwFlags, HCRYPTKEY *phKey) { @@ -750,6 +874,26 @@ BOOL WINAPI CryptDuplicateKey (HCRYPTKEY hKey, DWORD *pdwReserved, DWORD dwFlags /****************************************************************************** * CryptEncrypt (ADVAPI32.@) + * + * Encrypts data. + * + * PARAMS + * hKey [I] Handle to the enryption key. + * hHash [I] Handle to a hash object. + * Final [I] TRUE if this is the last section to encrypt. + * dwFlags [I] Can be CRYPT_OAEP. + * pbData [I/O] Data to be encrypted. Contains encrypted data after call. + * pdwDataLen [I/O] Length of the data to encrypt. Contains the length of the + * encrypted data after call. + * dwBufLen [I] Length of the input pbData buffer. + * + * RETURNS + * Success: TRUE + * Failure: FALSE + * + * NOTES + * If pbData is NULL, CryptEncrypt determines stores the number of bytes + * required for the returned data in pdwDataLen. */ BOOL WINAPI CryptEncrypt (HCRYPTKEY hKey, HCRYPTHASH hHash, BOOL Final, DWORD dwFlags, BYTE *pbData, DWORD *pdwDataLen, DWORD dwBufLen) @@ -770,6 +914,25 @@ BOOL WINAPI CryptEncrypt (HCRYPTKEY hKey, HCRYPTHASH hHash, BOOL Final, /****************************************************************************** * CryptEnumProvidersA (ADVAPI32.@) + * + * Returns the next availabe CPS. + * + * PARAMS + * dwIndex [I] Index of the next provider to be enumerated. + * pdwReserved [I] Reserved for future use and must be NULL. + * dwFlags [I] Reserved for future use and must be zero. + * pdwProvType [O] DWORD designating the type of the provider. + * pszProvName [O] Buffer that receives data from the provider. + * pcbProvName [I/O] Specifies the size of pszProvName. Contains the number + * of bytes stored in the buffer no return. + * + * RETURNS + * Success: TRUE + * Failure: FALSE + * + * NOTES + * If pszProvName is NULL, CryptEnumProvidersA sets the size of the name + * for memory allocation purposes. */ BOOL WINAPI CryptEnumProvidersA (DWORD dwIndex, DWORD *pdwReserved, DWORD dwFlags, DWORD *pdwProvType, LPSTR pszProvName, DWORD *pcbProvName) @@ -809,6 +972,8 @@ BOOL WINAPI CryptEnumProvidersA (DWORD dwIndex, DWORD *pdwReserved, /****************************************************************************** * CryptEnumProvidersW (ADVAPI32.@) + * + * see CryptEnumProvidersA */ BOOL WINAPI CryptEnumProvidersW (DWORD dwIndex, DWORD *pdwReserved, DWORD dwFlags, DWORD *pdwProvType, LPWSTR pszProvName, DWORD *pcbProvName) @@ -834,7 +999,26 @@ BOOL WINAPI CryptEnumProvidersW (DWORD dwIndex, DWORD *pdwReserved, } /****************************************************************************** - * CryptEnumProviderTypesA (ADVAPI32.@) + * CryptEnumProviderTypesA (ADVAPI32i.@) + * + * Retrieves the next type of CSP supported. + * + * PARAMS + * dwIndex [I] Index of the next provider to be enumerated. + * pdwReserved [I] Reserved for future use and must be NULL. + * dwFlags [I] Reserved for future use and must be zero. + * pdwProvType [O] DWORD designating the type of the provider. + * pszTypeName [O] Buffer that receives data from the provider type. + * pcbTypeName [I/O] Specifies the size of pszTypeName. Contains the number + * of bytes stored in the buffer no return. + * + * RETURNS + * Success: TRUE + * Failure: FALSE + * + * NOTES + * If pszTypeName is NULL, CryptEnumProviderTypesA sets the size of the name + * for memory allocation purposes. */ BOOL WINAPI CryptEnumProviderTypesA (DWORD dwIndex, DWORD *pdwReserved, DWORD dwFlags, DWORD *pdwProvType, LPSTR pszTypeName, DWORD *pcbTypeName) @@ -878,6 +1062,8 @@ BOOL WINAPI CryptEnumProviderTypesA (DWORD dwIndex, DWORD *pdwReserved, /****************************************************************************** * CryptEnumProviderTypesW (ADVAPI32.@) + * + * see CryptEnumProviderTypesA */ BOOL WINAPI CryptEnumProviderTypesW (DWORD dwIndex, DWORD *pdwReserved, DWORD dwFlags, DWORD *pdwProvType, LPWSTR pszTypeName, DWORD *pcbTypeName) @@ -903,6 +1089,24 @@ BOOL WINAPI CryptEnumProviderTypesW (DWORD dwIndex, DWORD *pdwReserved, /****************************************************************************** * CryptExportKey (ADVAPI32.@) + * + * Exports a cryptographic key from a CSP. + * + * PARAMS + * hKey [I] Handle to the key to export. + * hExpKey [I] Handle to a cryptographic key of the end user. + * dwBlobType [I] Type of BLOB to be exported. + * dwFlags [I] CRYPT_DESTROYKEY/SSL2_FALLBACK/OAEP. + * pbData [O] Buffer to receive BLOB data. + * pdwDataLen [I/O] Specifies the size of pbData. + * + * RETURNS + * Success: TRUE + * Failure: FALSE + * + * NOTES + * if pbData is NULL, CryptExportKey sets pdwDataLen as the size of the + * buffer needed to hold the BLOB. */ BOOL WINAPI CryptExportKey (HCRYPTKEY hKey, HCRYPTKEY hExpKey, DWORD dwBlobType, DWORD dwFlags, BYTE *pbData, DWORD *pdwDataLen) @@ -922,6 +1126,18 @@ BOOL WINAPI CryptExportKey (HCRYPTKEY hKey, HCRYPTKEY hExpKey, DWORD dwBlobType, /****************************************************************************** * CryptGenKey (ADVAPI32.@) + * + * Generates a random cryptographic session key or a pub/priv key pair. + * + * PARAMS + * hProv [I] Handle to a CSP. + * Algid [I] Algorithm to use to make key. + * dwFlags [I] Specifies type of key to make. + * phKey [I] Address of the handle to which the new key is copied. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptGenKey (HCRYPTPROV hProv, ALG_ID Algid, DWORD dwFlags, HCRYPTKEY *phKey) { @@ -952,6 +1168,23 @@ BOOL WINAPI CryptGenKey (HCRYPTPROV hProv, ALG_ID Algid, DWORD dwFlags, HCRYPTKE /****************************************************************************** * CryptGetDefaultProviderA (ADVAPI32.@) + * + * Finds the default CSP of a certain provider type. + * + * PARAMS + * dwProvType [I] Provider type to look for. + * pdwReserved [I] Reserved for future use and must be NULL. + * dwFlags [I] CRYPT_MACHINE_DEFAULT/USER_DEFAULT + * pszProvName [O] Name of the default CSP. + * pcbProvName [I/O] Size of pszProvName + * + * RETURNS + * Success: TRUE + * Failure: FALSE + * + * NOTES + * If pszProvName is NULL, pcbProvName will hold the size of the buffer for + * memory allocation purposes on return. */ BOOL WINAPI CryptGetDefaultProviderA (DWORD dwProvType, DWORD *pdwReserved, DWORD dwFlags, LPSTR pszProvName, DWORD *pcbProvName) @@ -985,6 +1218,8 @@ BOOL WINAPI CryptGetDefaultProviderA (DWORD dwProvType, DWORD *pdwReserved, /****************************************************************************** * CryptGetDefaultProviderW (ADVAPI32.@) + * + * see CryptGetDefaultProviderA */ BOOL WINAPI CryptGetDefaultProviderW (DWORD dwProvType, DWORD *pdwReserved, DWORD dwFlags, LPWSTR pszProvName, DWORD *pcbProvName) @@ -1010,6 +1245,22 @@ BOOL WINAPI CryptGetDefaultProviderW (DWORD dwProvType, DWORD *pdwReserved, /****************************************************************************** * CryptGetHashParam (ADVAPI32.@) + * + * Retrieves data that controls the operations of a hash object. + * + * PARAMS + * hHash [I] Handle of the hash object to question. + * dwParam [I] Query type. + * pbData [O] Buffer that receives the value data. + * pdwDataLen [I/O] Size of the pbData buffer. + * dwFlags [I] Reserved for future use and must be zero. + * + * RETURNS + * Success: TRUE + * Failure: FALSE + * + * NOTES + * If pbData is NULL, pdwDataLen will contain the length required. */ BOOL WINAPI CryptGetHashParam (HCRYPTHASH hHash, DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen, DWORD dwFlags) @@ -1029,6 +1280,22 @@ BOOL WINAPI CryptGetHashParam (HCRYPTHASH hHash, DWORD dwParam, BYTE *pbData, /****************************************************************************** * CryptGetKeyParam (ADVAPI32.@) + * + * Retrieves data that controls the operations of a key. + * + * PARAMS + * hKey [I] Handle to they key in question. + * dwParam [I] Specifies query type. + * pbData [O] Sequence of bytes to receive data. + * pdwDataLen [I/O] Size of pbData. + * dwFlags [I] Reserved for future use and must be zero. + * + * RETURNS + * Success: TRUE + * Failure: FALSE + * + * NOTES + * If pbData is NULL, pdwDataLen is set to the needed length of the buffer. */ BOOL WINAPI CryptGetKeyParam (HCRYPTKEY hKey, DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen, DWORD dwFlags) @@ -1048,6 +1315,22 @@ BOOL WINAPI CryptGetKeyParam (HCRYPTKEY hKey, DWORD dwParam, BYTE *pbData, /****************************************************************************** * CryptGetProvParam (ADVAPI32.@) + * + * Retrieves parameters that control the operations of a CSP. + * + * PARAMS + * hProv [I] Handle of the CSP in question. + * dwParam [I] Specifies query type. + * pbData [O] Buffer to receive the data. + * pdwDataLen [I/O] Size of pbData. + * dwFlags [I] see MSDN Docs. + * + * RETURNS + * Success: TRUE + * Failure: FALSE + * + * NOTES + * If pbData is NULL, pdwDataLen is set to the needed buffer length. */ BOOL WINAPI CryptGetProvParam (HCRYPTPROV hProv, DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen, DWORD dwFlags) @@ -1061,6 +1344,17 @@ BOOL WINAPI CryptGetProvParam (HCRYPTPROV hProv, DWORD dwParam, BYTE *pbData, /****************************************************************************** * CryptGetUserKey (ADVAPI32.@) + * + * Gets a handle of one of a user's two public/private key pairs. + * + * PARAMS + * hProv [I] Handle of a CSP. + * dwKeySpec [I] Private key to use. + * phUserKey [O] Pointer to the handle of the retrieved keys. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptGetUserKey (HCRYPTPROV hProv, DWORD dwKeySpec, HCRYPTKEY *phUserKey) { @@ -1091,6 +1385,18 @@ BOOL WINAPI CryptGetUserKey (HCRYPTPROV hProv, DWORD dwKeySpec, HCRYPTKEY *phUse /****************************************************************************** * CryptHashData (ADVAPI32.@) + * + * Adds data to a hash object. + * + * PARAMS + * hHash [I] Handle of the hash object. + * pbData [I] Buffer of data to be hashed. + * dwDataLen [I] Number of bytes to add. + * dwFlags [I] Can be CRYPT_USERDATA + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptHashData (HCRYPTHASH hHash, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags) { @@ -1110,6 +1416,15 @@ BOOL WINAPI CryptHashData (HCRYPTHASH hHash, BYTE *pbData, DWORD dwDataLen, DWOR /****************************************************************************** * CryptHashSessionKey (ADVAPI32.@) + * + * PARAMS + * hHash [I] Handle to the hash object. + * hKey [I] Handle to the key to be hashed. + * dwFlags [I] Can be CRYPT_LITTLE_ENDIAN. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptHashSessionKey (HCRYPTHASH hHash, HCRYPTKEY hKey, DWORD dwFlags) { @@ -1128,6 +1443,18 @@ BOOL WINAPI CryptHashSessionKey (HCRYPTHASH hHash, HCRYPTKEY hKey, DWORD dwFlags /****************************************************************************** * CryptImportKey (ADVAPI32.@) + * + * PARAMS + * hProv [I] Handle of a CSP. + * pbData [I] Contains the key to be imported. + * dwDataLen [I] Length of the key. + * hPubKey [I] Cryptographic key that decrypts pdData + * dwFlags [I] Used only with a public/private key pair. + * phKey [O] Imported key. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptImportKey (HCRYPTPROV hProv, BYTE *pbData, DWORD dwDataLen, HCRYPTKEY hPubKey, DWORD dwFlags, HCRYPTKEY *phKey) @@ -1165,6 +1492,20 @@ BOOL WINAPI CryptImportKey (HCRYPTPROV hProv, BYTE *pbData, DWORD dwDataLen, * * CryptSignHashA (ADVAPI32.@) * CryptSignHashW (ADVAPI32.@) + * + * Signs data. + * + * PARAMS + * hHash [I] Handle of the hash object to be signed. + * dwKeySpec [I] Private key to use. + * sDescription [I] Must be NULL. + * dwFlags [I] CRYPT_NOHASHOID/X931_FORMAT. + * pbSignature [O] Buffer of the signature data. + * pdwSigLen [I/O] Size of the pbSignature buffer. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptSignHashA (HCRYPTHASH hHash, DWORD dwKeySpec, LPCSTR sDescription, DWORD dwFlags, BYTE *pbSignature, DWORD *pdwSigLen) @@ -1188,6 +1529,18 @@ BOOL WINAPI CryptSignHashA (HCRYPTHASH hHash, DWORD dwKeySpec, LPCSTR sDescripti /****************************************************************************** * CryptSetHashParam (ADVAPI32.@) + * + * Customizes the operations of a hash object. + * + * PARAMS + * hHash [I] Handle of the hash object to set parameters. + * dwParam [I] HP_HMAC_INFO/HASHVAL. + * pbData [I] Value data buffer. + * dwFlags [I] Reserved for future use and must be zero. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptSetHashParam (HCRYPTHASH hHash, DWORD dwParam, BYTE *pbData, DWORD dwFlags) { @@ -1206,6 +1559,18 @@ BOOL WINAPI CryptSetHashParam (HCRYPTHASH hHash, DWORD dwParam, BYTE *pbData, DW /****************************************************************************** * CryptSetKeyParam (ADVAPI32.@) + * + * Customizes a session key's operations. + * + * PARAMS + * hKey [I] Handle to the key to set values. + * dwParam [I] See MSDN Doc. + * pbData [I] Buffer of values to set. + * dwFlags [I] Only used when dwParam == KP_ALGID. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptSetKeyParam (HCRYPTKEY hKey, DWORD dwParam, BYTE *pbData, DWORD dwFlags) { @@ -1224,6 +1589,16 @@ BOOL WINAPI CryptSetKeyParam (HCRYPTKEY hKey, DWORD dwParam, BYTE *pbData, DWORD /****************************************************************************** * CryptSetProviderA (ADVAPI32.@) + * + * Specifies the current user's default CSP. + * + * PARAMS + * pszProvName [I] Name of the new default CSP. + * dwProvType [I] Provider type of the CSP. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptSetProviderA (LPCSTR pszProvName, DWORD dwProvType) { @@ -1233,6 +1608,8 @@ BOOL WINAPI CryptSetProviderA (LPCSTR pszProvName, DWORD dwProvType) /****************************************************************************** * CryptSetProviderW (ADVAPI32.@) + * + * See CryptSetProviderA */ BOOL WINAPI CryptSetProviderW (LPCWSTR pszProvName, DWORD dwProvType) { @@ -1242,6 +1619,18 @@ BOOL WINAPI CryptSetProviderW (LPCWSTR pszProvName, DWORD dwProvType) /****************************************************************************** * CryptSetProviderExA (ADVAPI32.@) + * + * Specifies the default CSP. + * + * PARAMS + * pszProvName [I] Name of the new default CSP. + * dwProvType [I] Provider type of the CSP. + * pdwReserved [I] Reserved for future use and must be NULL. + * dwFlags [I] See MSDN Doc. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptSetProviderExA (LPCSTR pszProvName, DWORD dwProvType, DWORD *pdwReserved, DWORD dwFlags) { @@ -1287,6 +1676,8 @@ BOOL WINAPI CryptSetProviderExA (LPCSTR pszProvName, DWORD dwProvType, DWORD *pd /****************************************************************************** * CryptSetProviderExW (ADVAPI32.@) + * + * See CryptSetProviderExA */ BOOL WINAPI CryptSetProviderExW (LPCWSTR pszProvName, DWORD dwProvType, DWORD *pdwReserved, DWORD dwFlags) { @@ -1305,6 +1696,18 @@ BOOL WINAPI CryptSetProviderExW (LPCWSTR pszProvName, DWORD dwProvType, DWORD *p /****************************************************************************** * CryptSetProvParam (ADVAPI32.@) + * + * Customizes the operations of a CSP. + * + * PARAMS + * hProv [I] Handle of a CSP. + * dwParam [I] See MSDN Doc. + * pbData [I] Buffer that contains a value to set as a parameter. + * dwFlags [I] if dwParam is PP_USE_HARDWARE_RNG, dwFlags must be zero. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptSetProvParam (HCRYPTPROV hProv, DWORD dwParam, BYTE *pbData, DWORD dwFlags) { @@ -1345,6 +1748,20 @@ BOOL WINAPI CryptSetProvParam (HCRYPTPROV hProv, DWORD dwParam, BYTE *pbData, DW * * CryptVerifySignatureA (ADVAPI32.@) * CryptVerifySignatureW (ADVAPI32.@) + * + * Verifies the signature of a hash object. + * + * PARAMS + * hHash [I] Handle of the hash object to verify. + * pbSignature [I] Signature data to verify. + * dwSigLen [I] Size of pbSignature. + * hPubKey [I] Handle to the public key to authenticate signature. + * sDescription [I] Must be set to NULL. + * dwFlags [I] See MSDN doc. + * + * RETURNS + * Success: TRUE + * Failure: FALSE */ BOOL WINAPI CryptVerifySignatureA (HCRYPTHASH hHash, BYTE *pbSignature, DWORD dwSigLen, HCRYPTKEY hPubKey, LPCSTR sDescription, DWORD dwFlags) diff --git a/dlls/advapi32/eventlog.c b/dlls/advapi32/eventlog.c index 6260687644b..ee7f9652fbd 100644 --- a/dlls/advapi32/eventlog.c +++ b/dlls/advapi32/eventlog.c @@ -35,6 +35,17 @@ WINE_DECLARE_DEBUG_CHANNEL(eventlog); /****************************************************************************** * BackupEventLogA [ADVAPI32.@] + * + * Saves the event log to a backup file. + * + * PARAMS + * hEventLog [I] Handle to event log to backup. + * lpBackupFileName [I] Name of the backup file. + * + * RETURNS + * Success: nonzero. File lpBackupFileName will contain the contents of + * hEvenLog. + * Failure: zero. */ BOOL WINAPI BackupEventLogA( HANDLE hEventLog, LPCSTR lpBackupFileName ) { @@ -45,9 +56,7 @@ BOOL WINAPI BackupEventLogA( HANDLE hEventLog, LPCSTR lpBackupFileName ) /****************************************************************************** * BackupEventLogW [ADVAPI32.@] * - * PARAMS - * hEventLog [] - * lpBackupFileName [] + * see BackupEventLogA */ BOOL WINAPI BackupEventLogW( HANDLE hEventLog, LPCWSTR lpBackupFileName ) @@ -58,6 +67,18 @@ BackupEventLogW( HANDLE hEventLog, LPCWSTR lpBackupFileName ) /****************************************************************************** * ClearEventLogA [ADVAPI32.@] + * + * Clears the event log and/or saves the log to a backup file. + * + * PARAMS + * hEvenLog [I] Handle to event log to clear. + * lpBackupFileName [I] Name of the backup file. + * + * RETURNS + * Success: nonzero. if lpBackupFileName != NULL, lpBackupFileName will + * contain the contents of hEvenLog and the log will be cleared. + * Failure: zero. Fails if the event log is empty or if lpBackupFileName + * exists. */ BOOL WINAPI ClearEventLogA ( HANDLE hEventLog, LPCSTR lpBackupFileName ) { @@ -67,6 +88,8 @@ BOOL WINAPI ClearEventLogA ( HANDLE hEventLog, LPCSTR lpBackupFileName ) /****************************************************************************** * ClearEventLogW [ADVAPI32.@] + * + * see ClearEventLogA */ BOOL WINAPI ClearEventLogW ( HANDLE hEventLog, LPCWSTR lpBackupFileName ) { @@ -76,6 +99,15 @@ BOOL WINAPI ClearEventLogW ( HANDLE hEventLog, LPCWSTR lpBackupFileName ) /****************************************************************************** * CloseEventLog [ADVAPI32.@] + * + * Closes a read handle to the event log. + * + * PARAMS + * hEventLog [I/O] Handle of the event log to close. + * + * RETURNS + * Success: nonzero + * Failure: zero */ BOOL WINAPI CloseEventLog ( HANDLE hEventLog ) { @@ -85,12 +117,15 @@ BOOL WINAPI CloseEventLog ( HANDLE hEventLog ) /****************************************************************************** * DeregisterEventSource [ADVAPI32.@] - * Closes a handle to the specified event log + * + * Closes a write handle to an event log * * PARAMS - * hEventLog [I] Handle to event log + * hEventLog [I/O] Handle of the event log. * - * RETURNS STD + * RETURNS + * Success: nonzero + * Failure: zero */ BOOL WINAPI DeregisterEventSource( HANDLE hEventLog ) { @@ -101,9 +136,16 @@ BOOL WINAPI DeregisterEventSource( HANDLE hEventLog ) /****************************************************************************** * GetNumberOfEventLogRecords [ADVAPI32.@] * + * Retrieves the number of records in an event log. + * * PARAMS - * hEventLog [] - * NumberOfRecords [] + * hEventLog [I] Handle to an open event log. + * NumberOfRecords [O] Number of records in the log. + * + * RETURNS + * Success: nonzero. NumberOfRecords will contain the number of records in + * the log. + * Failure: zero */ BOOL WINAPI GetNumberOfEventLogRecords( HANDLE hEventLog, PDWORD NumberOfRecords ) @@ -115,9 +157,16 @@ GetNumberOfEventLogRecords( HANDLE hEventLog, PDWORD NumberOfRecords ) /****************************************************************************** * GetOldestEventLogRecord [ADVAPI32.@] * + * Retrieves the absolute record number of the oldest record in an even log. + * * PARAMS - * hEventLog [] - * OldestRecord [] + * hEventLog [I] Handle to an open event log. + * OldestRecord [O] Absolute record number of the oldest record. + * + * RETURNS + * Success: nonzero. OldestRecord contains the record number of the oldest + * record in the log. + * Failure: zero */ BOOL WINAPI GetOldestEventLogRecord( HANDLE hEventLog, PDWORD OldestRecord ) @@ -129,9 +178,16 @@ GetOldestEventLogRecord( HANDLE hEventLog, PDWORD OldestRecord ) /****************************************************************************** * NotifyChangeEventLog [ADVAPI32.@] * + * Enables an application to receive notification when an event is written + * to an event log. + * * PARAMS - * hEventLog [] - * hEvent [] + * hEventLog [I] Handle to an event log. + * hEvent [I] Handle to a manual-reset event object. + * + * RETURNS + * Success: nonzero + * Failure: zero */ BOOL WINAPI NotifyChangeEventLog( HANDLE hEventLog, HANDLE hEvent ) { @@ -141,6 +197,17 @@ BOOL WINAPI NotifyChangeEventLog( HANDLE hEventLog, HANDLE hEvent ) /****************************************************************************** * OpenBackupEventLogA [ADVAPI32.@] + * + * Opens a handle to a backup event log. + * + * PARAMS + * lpUNCServerName [I] Universal Naming Convention name of the server on which + * this will be performed. + * lpFileName [I] Specifies the name of the backup file. + * + * RETURNS + * Success: Handle to the backup event log. + * Failure: NULL */ HANDLE WINAPI OpenBackupEventLogA( LPCSTR lpUNCServerName, LPCSTR lpFileName ) @@ -152,9 +219,7 @@ OpenBackupEventLogA( LPCSTR lpUNCServerName, LPCSTR lpFileName ) /****************************************************************************** * OpenBackupEventLogW [ADVAPI32.@] * - * PARAMS - * lpUNCServerName [] - * lpFileName [] + * see OpenBackupEventLogA */ HANDLE WINAPI OpenBackupEventLogW( LPCWSTR lpUNCServerName, LPCWSTR lpFileName ) @@ -165,6 +230,17 @@ OpenBackupEventLogW( LPCWSTR lpUNCServerName, LPCWSTR lpFileName ) /****************************************************************************** * OpenEventLogA [ADVAPI32.@] + * + * Opens a handle to the specified event log. + * + * PARAMS + * lpUNCServerName [I] UNC name of the server on which the event log is + * opened. + * lpSourceName [I] Name of the log. + * + * RETURNS + * Success: Handle to an event log. + * Failure: NULL */ HANDLE WINAPI OpenEventLogA(LPCSTR uncname,LPCSTR source) { @@ -175,9 +251,7 @@ HANDLE WINAPI OpenEventLogA(LPCSTR uncname,LPCSTR source) /****************************************************************************** * OpenEventLogW [ADVAPI32.@] * - * PARAMS - * uncname [] - * source [] + * see OpenEventLogA */ HANDLE WINAPI OpenEventLogW( LPCWSTR uncname, LPCWSTR source ) @@ -188,6 +262,22 @@ OpenEventLogW( LPCWSTR uncname, LPCWSTR source ) /****************************************************************************** * ReadEventLogA [ADVAPI32.@] + * + * Reads a whole number of entries from an event log. + * + * PARAMS + * hEventLog [I] Handle of the event log to read. + * dwReadFlags [I] see MSDN doc. + * dwRecordOffset [I] Log-entry record number to start at. + * lpBuffer [O] Buffer for the data read. + * nNumberOfBytesToRead [I] Size of lpBuffer. + * pnBytesRead [O] Receives number of bytes read. + * pnMinNumberOfBytesNeeded [O] Receives number of bytes required for the + * next log entry. + * + * RETURNS + * Success: nonzero + * Failure: zero */ BOOL WINAPI ReadEventLogA( HANDLE hEventLog, DWORD dwReadFlags, DWORD dwRecordOffset, LPVOID lpBuffer, DWORD nNumberOfBytesToRead, DWORD *pnBytesRead, DWORD *pnMinNumberOfBytesNeeded ) @@ -199,14 +289,7 @@ BOOL WINAPI ReadEventLogA( HANDLE hEventLog, DWORD dwReadFlags, DWORD dwRecordOf /****************************************************************************** * ReadEventLogW [ADVAPI32.@] * - * PARAMS - * hEventLog [] - * dwReadFlags [] - * dwRecordOffset [] - * lpBuffer [] - * nNumberOfBytesToRead [] - * pnBytesRead [] - * pnMinNumberOfBytesNeeded [] + * see ReadEventLogA */ BOOL WINAPI ReadEventLogW( HANDLE hEventLog, DWORD dwReadFlags, DWORD dwRecordOffset, @@ -219,6 +302,17 @@ ReadEventLogW( HANDLE hEventLog, DWORD dwReadFlags, DWORD dwRecordOffset, /****************************************************************************** * RegisterEventSourceA [ADVAPI32.@] + * + * Returns a registered handle to an event log. + * + * PARAMS + * lpUNCServerName [I] UNC name of the source server. + * lpSourceName [I] Specifies the name of the event source to retrieve. + * + * RETURNS + * Success: Handle to the event log. + * Failure: NULL. Returns ERROR_INVALID_HANDLE if lpSourceName specifies the + * Security event log. */ HANDLE WINAPI RegisterEventSourceA( LPCSTR lpUNCServerName, LPCSTR lpSourceName ) { @@ -236,15 +330,8 @@ HANDLE WINAPI RegisterEventSourceA( LPCSTR lpUNCServerName, LPCSTR lpSourceName /****************************************************************************** * RegisterEventSourceW [ADVAPI32.@] - * Returns a registered handle to an event log * - * PARAMS - * lpUNCServerName [I] Server name for source - * lpSourceName [I] Source name for registered handle - * - * RETURNS - * Success: Handle - * Failure: NULL + * see RegisterEventSourceA */ HANDLE WINAPI RegisterEventSourceW( LPCWSTR lpUNCServerName, LPCWSTR lpSourceName ) @@ -256,6 +343,28 @@ RegisterEventSourceW( LPCWSTR lpUNCServerName, LPCWSTR lpSourceName ) /****************************************************************************** * ReportEventA [ADVAPI32.@] + * + * Writes an entry at the end of an event log. + * + * PARAMS + * hEventLog [I] Handle of an event log. + * wType [I] See MSDN doc. + * wCategory [I] Event category. + * dwEventID [I] Event identifier. + * lpUserSid [I] Current user's security identifier. + * wNumStrings [I] Number of insert strings in lpStrings. + * dwDataSize [I] Size of event-specific raw data to write. + * lpStrings [I] Buffer containing an array of string to be merged. + * lpRawData [I] Buffer containing the binary data. + * + * RETURNS + * Success: nonzero. Entry was written to the log. + * Failure: zero. + * + * NOTES + * The ReportEvent function adds the time, the entry's length, and the + * offsets before storing the entry in the log. If lpUserSid != NULL, the + * username is also logged. */ BOOL WINAPI ReportEventA ( HANDLE hEventLog, WORD wType, WORD wCategory, DWORD dwEventID, PSID lpUserSid, WORD wNumStrings, DWORD dwDataSize, LPCSTR *lpStrings, LPVOID lpRawData) @@ -287,16 +396,7 @@ BOOL WINAPI ReportEventA ( HANDLE hEventLog, WORD wType, WORD wCategory, DWORD d /****************************************************************************** * ReportEventW [ADVAPI32.@] * - * PARAMS - * hEventLog [] - * wType [] - * wCategory [] - * dwEventID [] - * lpUserSid [] - * wNumStrings [] - * dwDataSize [] - * lpStrings [] - * lpRawData [] + * see ReportEventA */ BOOL WINAPI ReportEventW( HANDLE hEventLog, WORD wType, WORD wCategory,