CryptEncodeObjectEx

Article
06/30/2006

This function encodes a structure of the type indicated by the value of the lpszStructType parameter. The CryptEncodeObjectEx function offers a significant performance improvement over the CryptEncodeObject function by supporting memory allocation with the CRYPT_ENCODE_ALLOC_FLAG value.

BOOL WINAPI CryptEncodeObjectEx(
DWORD dwCertEncodingType, 
LPCSTR lpszStructType, 
const void *pvStructInfo, 
DWORD dwFlags, 
PCRYPT_ENCODE_PARA pEncodePara, 
void *pvEncoded, 
DWORD *pcbEncoded
);

Parameters

dwCertEncodingType
[in] Type of encoding used. Currently, only X509_ASN_ENCODING is used; however, additional encoding types may be added in the future.

Note Either a certificate or message encoding type is required. X509_ASN_ENCODING is the default. If that type is indicated, it is used. Otherwise, if the PKCS7_ASN_ENCODING type is indicated, it is used.
lpszStructType
[in] Pointer to an OID defining the structure type. If the high-order word of the lpszStructType parameter is zero, the low-order word specifies an integer identifier for the type of the specified structure. Otherwise, this parameter is a long pointer to a NULL-terminated string.

For more details about object identifier strings, their predefined constants, and their corresponding structures, see Constants for the CryptEncodeObjectEx and CryptDecodeObjectEx functions.
pvStructInfo
[in] Pointer to the structure to be encoded. The structure must be of the type specified by the lpszStructType parameter.

dwFlags
[in] The following table defines the dwFlags flags that can be combined with bitwise OR operations.

Value	Description
CRYPT_ENCODE_ALLOC_FLAG	The called encoding function allocates memory for the encoded bytes. A pointer to the allocated bytes is returned in the pvEncoded parameter. If pEncodePara or pEncodePara->pfnAlloc is NULL, then the LocalAlloc function is called for the allocation and the LocalFree function must be called to free the memory. If pEncodePara and pEncodePara->pfnAlloc are non-NULL, then pEncodePara->pfnAlloc is called for the allocation and the function pointed to by pEncodePara->pfnFree must be called to free the memory.
CRYPT_UNICODE_NAME_ENCODE_ENABLE_T61_UNICODE_FLAG	This flag is applicable when encoding X509_UNICODE_NAME. If this flag is set and all the Unicode characters are <= 0xFF, CERT_RDN_T61_STRING is selected instead of CERT_RDN_UNICODE_STRING.
CRYPT_UNICODE_NAME_ENCODE_DISABLE_CHECK_TYPE_FLAG	This flag is applicable when encoding X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE, or X509_UNICODE_ANY_STRING. If this flag is set, the characters are not checked to see if they are valid for the specified value type.
CRYPT_UNICODE_NAME_ENCODE_ENABLE_UTF8_UNICODE_FLAG	This flag is applicable when encoding an X509_UNICODE_NAME. When set, CERT_RDN_UTF8_STRING is selected instead of CERT_RDN_UNICODE_STRING.

pEncodePara
[in] Optional pointer to a CRYPT_ENCODE_PARA structure containing encoding information. If the pEncodePara parameter is set to NULL, the LocalAlloc and LocalFree functions are used to allocate and free memory. If the pEncodePara parameter points to a CRYPT_ENCODE_PARA structure, that structure passes in callback functions to allocate and free memory. These function override the default memory allocation of the LocalAlloc and LocalFree functions.
pvEncoded
[out] Pointer to a buffer to receive the encoded structure. When the buffer that is specified is not large enough to receive the decoded structure, the function sets the ERROR_MORE_DATA code and stores the required buffer size, in bytes, in the variable pointed to by the pcbEncoded parameter.

The pvEncoded parameter can be NULL to retrieve the size of the buffer for memory allocation purposes.

If the dwFlags parameter is set to CRYPT_ENCODE_ALLOC_FLAG, the pvEncoded parameter is not a pointer to a buffer but is the address of a pointer to the buffer. Because memory is allocated inside the function and the pointer is stored at *pvEncoded, the pvEncoded parameter must always be non-NULL.
pcbEncoded
[in/out] Pointer to a DWORD that contains the size, in bytes, of the buffer pointed to by the pvEncoded parameter. When the function returns, the variable pointed to by the pcbEncoded parameter contains the number of allocated, encoded bytes stored in the buffer.

When CRYPT_ENCODE_ALLOC_FLAG is set, the pcbEncoded parameter is the address of a pointer to the DWORD that is updated.

Note When processing the data returned in the buffer, applications must use the actual size of the data returned. The actual size can be slightly smaller than the size of the buffer specified on input. (On input, buffer sizes are usually specified large enough to ensure that the largest possible output data fits in the buffer.) On output, the variable pointed to by this parameter is updated to reflect the actual size of the data copied to the buffer.

Return Values

If the function succeeds, the return value is nonzero (TRUE).

If the function fails, the return value is zero (FALSE).

For extended error information, call the GetLastError function. The following table shows a list of some possible error codes.

Value	Description
CRYPT_E_BAD_ENCODE	An error was encountered while decoding.
ERROR_FILE_NOT_FOUND	A decoding function could not be found for the specified dwCertEncodingType and lpszStructType parameters.
ERROR_MORE_DATA	If the buffer specified by the pvStructInfo parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code and stores the required buffer size, in bytes, in the variable pointed to by the pcbStructInfo parameter.

Remarks

The CryptEncodeObjectEx function first looks for an installable extended encoding function. If no extended encoding function is found, the old, nonextended, installable function is located.

The desktop platform supports the PKCS_7_ASN_ENCODING flag, but Windows CE does not. Windows CE ignores the flag when it is specified.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	3.0 or later	Wincrypt.h		Crypt32.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

Last updated on Tuesday, July 13, 2004

CryptEncodeObjectEx

Additional resources