Função CryptEncodeObject (wincrypt.h)

  • Artigo

A função CryptEncodeObject codifica uma estrutura do tipo indicado pelo valor do parâmetro lpszStructType . O uso de CryptEncodeObjectEx é recomendado como uma API que executa a mesma função com melhorias significativas de desempenho.

Sintaxe

BOOL CryptEncodeObject(
  [in]      DWORD      dwCertEncodingType,
  [in]      LPCSTR     lpszStructType,
  [in]      const void *pvStructInfo,
  [out]     BYTE       *pbEncoded,
  [in, out] DWORD      *pcbEncoded
);

Parâmetros

[in] dwCertEncodingType

Tipo de codificação usada. É sempre aceitável especificar os tipos de codificação de certificado e mensagem combinando-os com uma operação OR bit a bit, conforme mostrado no exemplo a seguir:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

Os tipos de codificação definidos no momento são:

  • X509_ASN_ENCODING
  • PKCS_7_ASN_ENCODING
Nota Um tipo de codificação de certificado ou mensagem é necessário. X509_ASN_ENCODING é o padrão. Se esse tipo for indicado, ele será usado. Caso contrário, se o tipo PKCS7_ASN_ENCODING for indicado, ele será usado.
 

[in] lpszStructType

Um ponteiro para um OID que define o tipo de estrutura. Se a palavra de alta ordem do parâmetro lpszStructType for zero, a palavra de ordem baixa especificará o identificador inteiro para o tipo da estrutura especificada. Caso contrário, esse parâmetro é um ponteiro longo para uma cadeia de caracteres terminada em nulo.

Para obter mais informações sobre cadeias de caracteres de identificador de objeto, suas constantes predefinidas e estruturas correspondentes, consulte Constantes para CryptEncodeObject e CryptDecodeObject.

[in] pvStructInfo

Um ponteiro para a estrutura a ser codificada. A estrutura deve ser de um tipo especificado por lpszStructType.

[out] pbEncoded

Um ponteiro para um buffer para receber a estrutura codificada. Quando o buffer especificado não é grande o suficiente para receber a estrutura decodificada, a função define o código ERROR_MORE_DATA e armazena o tamanho do buffer necessário, em bytes, na variável apontada por pcbEncoded.

Esse parâmetro pode ser NULL para recuperar o tamanho dessas informações para fins de alocação de memória. Para obter mais informações, consulte Recuperando dados de comprimento desconhecido.

[in, out] pcbEncoded

Um ponteiro para uma variável DWORD que contém o tamanho, em bytes, do buffer apontado pelo parâmetro pbEncoded . Quando a função retorna, o valor DWORD contém o número de bytes codificados alocados armazenados no buffer.

Nota Ao processar os dados retornados no buffer, os aplicativos devem usar o tamanho real dos dados retornados. O tamanho real pode ser ligeiramente menor do que o tamanho do buffer especificado na entrada. (Na entrada, os tamanhos de buffer geralmente são especificados grandes o suficiente para garantir que os maiores dados de saída possíveis caibam no buffer.) Na saída, a variável apontada por esse parâmetro é atualizada para refletir o tamanho real dos dados copiados para o buffer.
 

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero (TRUE).

Se a função falhar, o valor retornado será zero (FALSE). Para obter informações de erro estendidas, chame GetLastError. Alguns códigos de erro possíveis estão listados na tabela a seguir.

Código de retorno Descrição
CRYPT_E_BAD_ENCODE
 Erro ao codificar.
ERROR_FILE_NOT_FOUND
 Não foi possível encontrar uma função de codificação para dwCertEncodingType e lpszStructType especificados.
ERROR_MORE_DATA
 Se o buffer especificado pelo parâmetro pbEncoded não for grande o suficiente para manter os dados retornados, a função definirá o código ERROR_MORE_DATA e armazenará o tamanho do buffer necessário, em bytes, na variável apontada por pcbEncoded.
 

Se a função falhar, GetLastError poderá retornar um erro de codificação/decodificação ASN.1 ( Abstract Syntax Notation One ). Para obter informações sobre esses erros, consulte Valores retornados de codificação/decodificação asn.1.

Comentários

Ao codificar um objeto criptográfico usando a função CryptEncodeObjectEx preferencial, o caractere NULL de terminação é incluído. Ao decodificar, usando a função CryptDecodeObjectEx preferencial, o caractere NULL de terminação não é mantido.

Exemplos

Para obter um exemplo que usa essa função, consulte Exemplo de programa C: fazendo uma solicitação de certificado e exemplo de programa C: codificação e decodificação ASN.1.

Requisitos

   
Cliente mínimo com suporte Windows XP [aplicativos da área de trabalho | aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho wincrypt.h
Biblioteca Crypt32.lib
DLL Crypt32.dll

Confira também

Cryptdecodeobject

CryptEncodeObjectEx

Funções de codificação e decodificação de objeto