LoginIScsiTargetA function (iscsidsc.h)
The LoginIscsiTarget function establishes a full featured login session with the indicated target.
Syntax
ISDSC_STATUS ISDSC_API LoginIScsiTargetA(
[in] PSTR TargetName,
[in] BOOLEAN IsInformationalSession,
[in, optional] PSTR InitiatorInstance,
[in, optional] ULONG InitiatorPortNumber,
[in, optional] PISCSI_TARGET_PORTALA TargetPortal,
[in, optional] ISCSI_SECURITY_FLAGS SecurityFlags,
[in, optional] PISCSI_TARGET_MAPPINGA Mappings,
[in, optional] PISCSI_LOGIN_OPTIONS LoginOptions,
[in, optional] ULONG KeySize,
[in, optional] PCHAR Key,
[in] BOOLEAN IsPersistent,
[out] PISCSI_UNIQUE_SESSION_ID UniqueSessionId,
[out] PISCSI_UNIQUE_CONNECTION_ID UniqueConnectionId
);
Parameters
[in] TargetName
The name of the target with which to establish a login session. The target must already exist in the list of discovered targets for the iSCSI initiator service.
[in] IsInformationalSession
If true, the LoginIscsiTarget function establishes a login session, but the operation does not report the LUNs on the target to the "Plug and Play" Manager. If the login succeeds, management applications will be able to query the target for information with the SendScsiReportLuns and SendScsiReadCapacity functions, but the storage stack will not enumerate the target or load a driver for it.
If IsInformationalSession is false, LoginIscsiTarget reports the LUNs associated with the target to the "Plug and Play" Manager, and the system loads drivers for the LUNs.
[in, optional] InitiatorInstance
The name of the initiator that logs in to the target. If InitiatorName is null, the iSCSI initiator service selects an initiator.
[in, optional] InitiatorPortNumber
The port number of the Host Bus Adapter (HBA) that initiates the login session. If this parameter is ISCSI_ANY_INITIATOR_PORT, the caller did not specify a port for the initiator HBA to use when logging in to the target.
If InitiatorName is null, InitiatorPortNumber must be ISCSI_ANY_INITIATOR_PORT.
[in, optional] TargetPortal
Pointer to a structure of type ISCSI_TARGET_PORTAL that indicates the portal that the initiator uses to open the session. The specified portal must belong to a portal group that is associated with the TargetName. If TargetPortal is null, the iSCSI initiator service instructs the initiator to use any portal through which the target is accessible to the initiator. If the caller specifies the value for TargetPortal, the iSCSI initiator service will not verify that the TargetPortal is accessible to the initiator HBA.
[in, optional] SecurityFlags
A bitmap that specifies the characteristics of the IPsec connection that the initiator adds to the session. If an IPsec security policy between the initiator and the target portal is already configured as a result of the current portal group policy or a previous connection to the target, the existing configuration takes precedence over the configuration specified in SecurityFlags.
If the ISCSI_SECURITY_FLAG_VALID flag is set to 0, the iSCSI initiator service uses default values for the security flags that are defined in the registry.
Caller can set any of the following flags in the bitmap:
[in, optional] Mappings
An array of structures of type ISCSI_TARGET_MAPPING, each of which holds information that the initiator uses to assign bus, target and LUN numbers to the devices that are associated with the target. If Mappings is null, the initiator will select the bus, target and LUN numbers.
[in, optional] LoginOptions
A pointer to a structure of type ISCSI_LOGIN_OPTIONS that contains the options that specify the characteristics of the login session.
[in, optional] KeySize
The size, in bytes, of the target's preshared key specified by the Key parameter.
[in, optional] Key
A preshared key to use when logging in to the target portal that exposes this target.
[in] IsPersistent
If true, the initiator should save the characteristics of the login session in non-volatile storage, so that the information persists across restarts of the initiator device and reboots of the operating system. The initiator should not establish the login session until after saving the persistent data.
Whenever the initiator device restarts, it should automatically attempt to re-establish the login session with the same characteristics. If false, the initiator device simply logs in to the target without saving the characteristics of the login session.
[out] UniqueSessionId
A pointer to a structure of type ISCSI_UNIQUE_SESSION_ID that, on return, contains a unique session identifier for the login session.
[out] UniqueConnectionId
A pointer to a structure of type ISCSI_UNIQUE_CONNECTION_ID that, on return, contains a unique connection identifier for the login session.
Return value
Returns ERROR_SUCCESS if the operation succeeds. Otherwise, it returns the appropriate Win32 or iSCSI error code.
Remarks
The LoginIscsiTarget function either establishes a single login session with a target, or creates a persistent login to a target. If LoginIscsiTarget creates a persistent login, the specified initiator should log in to the target each time the initiator is started, typically at system boot. Callers to LoginIscsiTarget can request the creation of a persistent login by setting the IsPersistent parameter to true.
Note
The iscsidsc.h header defines LoginIScsiTarget 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 [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | iscsidsc.h |
| Library | Iscsidsc.lib |
| DLL | Iscsidsc.dll |