Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function encodes a structure of the type indicated by the value of the lpszStructTypeparameter. This function offers a significant performance improvement over the CryptEncodeObjectfunction by supporting memory allocation with the CRYPT_ENCODE_ALLOC_FLAG value.

Syntax 

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

Parameters

dwCertEncodingType

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

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 lpszStructTypeparameter 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.

pvStructInfo

[in] Pointer to the structure to be encoded. The structure must be of the type specified by the lpszStructTypeparameter.

dwFlags

[in] Bitmask of flags. The following table shows the flags that can be combined with bitwise ORoperations.

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 pvEncodedparameter.

If pEncodeParaor pEncodePara-> pfnAllocis NULL, then the LocalAllocfunction is called for the allocation and the LocalFreefunction must be called to free the memory.

If pEncodeParaand pEncodePara->pfnAllocare non-NULL, then pEncodePara-> pfnAllocis called for the allocation and the function pointed to by pEncodePara-> pfnFreemust 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 less than or equal to 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_PARAstructure containing encoding information. If the pEncodeParaparameter is set to NULL, the LocalAllocand LocalFreefunctions are used to allocate and free memory. If the pEncodeParaparameter points to a CRYPT_ENCODE_PARAstructure, that structure passes in callback functions to allocate and free memory. These functions override the default memory allocation of the LocalAllocand LocalFreefunctions.

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 pcbEncodedparameter.

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

If the dwFlagsparameter is set to CRYPT_ENCODE_ALLOC_FLAG, the pvEncodedparameter 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 pvEncodedparameter must always be non-NULL.

pcbEncoded

[in, out] On input, pointer to a DWORDthat contains the size, in bytes, of the buffer pointed to by the pvEncodedparameter. On output, the variable pointed to by the pcbEncodedparameter contains the number of allocated, encoded bytes stored in the buffer.

When CRYPT_ENCODE_ALLOC_FLAG is set, the pcbEncodedparameter is the address of a pointer to the DWORDthat is updated.

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 Value

If the function succeeds, the return value is nonzero, or TRUE.

If the function fails, the return value is zero, or FALSE.

For extended error information, call the GetLastErrorfunction. The following table shows a list of 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 dwCertEncodingTypeand lpszStructTypeparameters.

ERROR_MORE_DATA

If the buffer specified by the pvStructInfoparameter 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 pcbStructInfoparameter.

Remarks

This 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 operating system supports the flag PKCS_7_ASN_ENCODING, but Windows Embedded CE does not and ignores the flag when it is specified.

Requirements

Header wincrypt.h
Library crypt32.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also