Funzione CertStrToNameW (wincrypt.h)

La funzione CertStrToName converte una stringa X.500 con terminazione null in un nome certificato codificato.

Sintassi

BOOL CertStrToNameW(
  [in]            DWORD   dwCertEncodingType,
  [in]            LPCWSTR pszX500,
  [in]            DWORD   dwStrType,
  [in, optional]  void    *pvReserved,
  [out]           BYTE    *pbEncoded,
  [in, out]       DWORD   *pcbEncoded,
  [out, optional] LPCWSTR *ppszError
);

Parametri

[in] dwCertEncodingType

Tipo di codifica del certificato usato per codificare la stringa. L'identificatore del tipo di codifica del messaggio , contenuto nell'alto WORD di questo valore, viene ignorato da questa funzione.

Questo parametro può essere il seguente tipo di codifica del certificato attualmente definito.

[in] pszX500

Puntatore alla stringa X.500 con terminazione null da convertire. Il formato di questa stringa viene specificato dal parametro dwStrType .

Questa stringa deve essere formattata come l'output dalla funzione CertNameToStr .

[in] dwStrType

Questo parametro specifica il tipo della stringa. Questo parametro specifica anche altre opzioni per il contenuto della stringa.

Se non vengono combinati flag con l'identificatore di tipo stringa, la stringa può contenere una virgola (,) o un punto e virgola (;) come separatori nel nome distinto relativo (RDN) e un segno più (+) come separatore in più valori RDN.

Le virgolette ("") sono supportate. Una citazione può essere inclusa in un valore virgolette usando due set di virgolette, ad esempio CN="User ""one"".

Un valore che inizia con un segno di numero (#) viene considerato esadecimale ASCII e convertito in un CERT_RDN_OCTET_STRING. Lo spazio vuoto incorporato viene ignorato. Ad esempio, 1.2.3 = # AB CD 01 è uguale a 1.2.3=#ABCD01.

Spazio vuoto che circonda le chiavi, gli identificatori di oggetto e i valori vengono ignorati.

Questo parametro può avere uno dei valori seguenti.

Le opzioni seguenti possono essere combinate anche con il valore precedente per specificare opzioni aggiuntive per la stringa.

[in, optional] pvReserved

Riservato per l'uso futuro e deve essere NULL.

[out] pbEncoded

Puntatore a un buffer che riceve la struttura codificata.

Le dimensioni di questo buffer vengono specificate nel parametro pcbEncoded .

Questo parametro può essere NULL per ottenere le dimensioni necessarie del buffer a scopo di allocazione della memoria. Per altre informazioni, vedere Recupero dei dati di lunghezza sconosciuta.

[in, out] pcbEncoded

Puntatore a un DWORD che, prima di chiamare la funzione, contiene le dimensioni, in byte, del buffer a cui punta il parametro pbEncoded . Quando la funzione restituisce, la DWORD contiene il numero di byte archiviati nel buffer.

Se pbEncoded è NULL, la DWORD riceve le dimensioni, in byte, necessarie per il buffer.

[out, optional] ppszError

Puntatore a un puntatore di stringa che riceve informazioni di errore aggiuntive su una stringa di input non valida.

Se la stringa pszX500 non è valida, ppszError viene aggiornata da questa funzione per puntare all'inizio della sequenza di caratteri non valida. Se non vengono rilevati errori nella stringa di input, ppszError è impostato su NULL.

Se queste informazioni non sono necessarie, passare NULL per questo parametro.

Questo parametro viene aggiornato per i codici di errore seguenti restituiti da GetLastError.

CRYPT_E_INVALID_X500_STRING

CRYPT_E_INVALID_NUMERIC_STRING

CRYPT_E_INVALID_PRINTABLE_STRING

CRYPT_E_INVALID_IA5_STRING

Valore restituito

Restituisce un valore diverso da zero se ha esito positivo o zero in caso contrario.

Per informazioni sugli errori estesi, chiamare GetLastError.

Commenti

La tabella seguente contiene le chiavi X.500 supportate, la stringa dell'identificatore di oggetto corrispondente, l'identificatore stringa (da Wincrypt.h) e i tipi valore.

Se Printable o T61 è consentito come tipo di valore RDN per la chiave, Printable viene selezionato automaticamente se il componente stringa del nome è un membro dei set di caratteri seguenti:

• A, B, ..., Z
• a, b, ..., z
• 0, 1, ..., 9
• (spazio) ' ( ) + , - . / : = ?

I tipi T61 sono codificati con UTF8.

Esempio

Per un esempio che usa questa funzione, vedere Esempio di programma C: Conversione di nomi da certificati ad ASN.1 e Indietro.

Requisiti

Vedi anche

CertNameToStr

Funzioni di conversione dei dati

Getlasterror

Recupero di dati di lunghezza sconosciuta