DsCrackSpnA function (dsparse.h)

Article
02/09/2023

The DsCrackSpn function parses a service principal name (SPN) into its component strings.

Syntax

DSPARSE DWORD DsCrackSpnA(
  [in]                LPCSTR  pszSpn,
  [in, out, optional] LPDWORD pcServiceClass,
  [out, optional]     LPSTR   ServiceClass,
  [in, out, optional] LPDWORD pcServiceName,
  [out, optional]     LPSTR   ServiceName,
  [in, out, optional] LPDWORD pcInstanceName,
  [out, optional]     LPSTR   InstanceName,
  [out, optional]     USHORT  *pInstancePort
);

Parameters

[in] pszSpn

Pointer to a constant null-terminated string that contains the SPN to parse. The SPN has the following format, in which the <service class> and <instance name> components must be present and the <port number> and <service name> components are optional. The <port number> component must be a numeric string value.

<service class>/<instance name>:<port number>/<service name>

[in, out, optional] pcServiceClass

Pointer to a DWORD value that, on entry, contains the size, in TCHARs, of the ServiceClass buffer, including the terminating null character. On exit, this parameter contains the number of TCHARs in the ServiceClass string, including the terminating null character.

If this parameter is NULL, contains zero, or ServiceClass is NULL, this parameter and ServiceClass are ignored.

To obtain the number of characters required for the ServiceClass string, including the null terminator, call this function with a valid SPN, a non-NULL ServiceClass and this parameter set to 1.

[out, optional] ServiceClass

Pointer to a TCHAR buffer that receives a null-terminated string containing the <service class> component of the SPN. This buffer must be at least *pcServiceClass TCHARs in size. This parameter may be NULL if the service class is not required.

[in, out, optional] pcServiceName

Pointer to a DWORD value that, on entry, contains the size, in TCHARs, of the ServiceName buffer, including the terminating null character. On exit, this parameter contains the number of TCHARs in the ServiceName string, including the terminating null character.

If this parameter is NULL, contains zero, or ServiceName is NULL, this parameter and ServiceName are ignored.

To obtain the number of characters required for the ServiceName string, including the null terminator, call this function with a valid SPN, a non-NULL ServiceName and this parameter set to 1.

[out, optional] ServiceName

Pointer to a TCHAR buffer that receives a null-terminated string containing the <service name> component of the SPN. This buffer must be at least *pcServiceName TCHARs in size. If the <service name> component is not present in the SPN, this buffer receives the <instance name> component. This parameter may be NULL if the service name is not required.

[in, out, optional] pcInstanceName

Pointer to a DWORD value that, on entry, contains the size, in TCHARs, of the InstanceName buffer, including the terminating null character. On exit, this parameter contains the number of TCHARs in the InstanceName string, including the terminating null character.

If this parameter is NULL, contains zero, or InstanceName is NULL, this parameter and InstanceName are ignored.

To obtain the number of characters required for the InstanceName string, including the null terminator, call this function with a valid SPN, a non-NULL InstanceName and this parameter set to 1.

[out, optional] InstanceName

Pointer to a TCHAR buffer that receives a null-terminated string containing the <instance name> component of the SPN. This buffer must be at least *pcInstanceName TCHARs in size. This parameter may be NULL if the instance name is not required.

[out, optional] pInstancePort

Pointer to a DWORD value that receives the integer value of the <port number> component of the SPN. If the SPN does not contain a <port number> component, this parameter receives zero. This parameter may be NULL if the port number is not required.

Return value

Returns a Win32 error code, including the following.

Remarks

Note

The dsparse.h header defines DsCrackSpn as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	dsparse.h (include Ntdsapi.h)
Library	Ntdsapi.lib
DLL	Ntdsapi.dll