WinTrustSubjectGetName
[New
- Windows NT]
The WinTrustSubjectGetName
function retrieves the name of a subject from a PKCS #7 Signed Data certificate
that represents the subject. A trust provider can use the name to store and
retrieve certificates associated with the subject.
BOOL
WinTrustSubjectGetName(
|
LPWIN_TRUST_SIP_SUBJECT lpSubject, |
// pointer to description of the subject |
|
LPWIN_CERTIFICATE lpSignedData, |
// pointer to a signed data certificate |
|
LPWSTR lpBuffer, |
// pointer to a buffer that receives the subject
name |
|
LPDWORD lpRequiredLength |
// pointer to the size, in bytes, of the buffer |
|
); |
|
Parameters
lpSubject
Pointer to a WIN_TRUST_SIP_SUBJECT structure that identifies the
type of subject. Note that the function retrieves the subject s name from the lpSignedData
structure, not from the subject.
lpSignedData
Pointer to a WIN_CERTIFICATE structure that contains a
PKCS #7 Signed Data structure. The function retrieves the subject name from the
data associated with this structure.
lpBuffer
Pointer to a
buffer that receives a null-terminated, Unicode string that names the subject.
lpRequiredLength
Pointer to a DWORD.
On input, it specifies the size, in bytes, of the lpBuffer buffer. On
output, it receives the size, in bytes, of the returned string, including the
terminating null character. If the buffer is not large enough to hold the
string, the function fails, and lpRequiredLength returns the required
buffer size.
Return Values
If the
function succeeds, the return value is a nonzero value.
If the
function fails, the return value is zero. To get extended error information,
call GetLastError.
Remarks
A trust
provider calls the WinTrust implementation of the WinTrustSubjectGetName
function. WinTrust then calls the WinTrustSubjectGetName implementation
of the appropriate Subject Interface Package (SIP). The appropriate SIP is the
one registered to handle the type of subject specified by the lpSubject
parameter.
Each Subject
Interface Package (SIP) DLL must implement the WinTrustSubjectGetName
function. WinTrust gets a pointer to the SIP s WinTrustSubjectGetName
implementation when WinTrust calls the SIP s WinTrustSipInitialize initialization function.
A SIP s implementation
of WinTrustSubjectGetName returns a name associated with the subject.
This may be a filename, if the subject is a file, or some other string that
identifies the subject. The purpose of this function is to provide a string
that a trust provider can use to store and retrieve certificates associated
with the subject. The name does not need to be unique, but it should identify
the subject and be the same each time it is retrieved.
The
LPWINTRUST_SUBJECT_GET_NAME type is a pointer to a WinTrustSubjectGetName
function.
See Also