LoginIscsiTarget function

The LoginIscsiTarget function establishes a full featured login session with the indicated target.

Syntax


HRESULT WINAPI LoginIscsiTarget(
  _In_      PTCHAR TargetName,
  _In_      BOOLEAN IsInformationalSession,
  _In_opt_  PTCHAR InitiatorName,
  _In_opt_  ULONG InitiatorPortNumber,
  _In_opt_  PISCSI_TARGET_PORTAL TargetPortal,
  _In_opt_  ISCSI_SECURITY_FLAGS SecurityFlags,
  _In_opt_  PISCSI_TARGET_MAPPING Mappings,
  _In_opt_  PISCSI_LOGIN_OPTIONS LoginOptions,
  _In_opt_  ULONG KeySize,
  _In_opt_  PCHAR Key,
  _In_      BOOLEAN IsPersistent,
  _Out_     PISCSI_UNIQUE_SESSION_ID UniqueSessionId,
  _Out_     PISCSI_UNIQUE_CONNECTION_ID UniqueConnectionId
);

Parameters

TargetName [in]

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.

IsInformationalSession [in]

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.

InitiatorName [in, optional]

The name of the initiator that logs in to the target. If InitiatorName is null, the iSCSI initiator service selects an initiator.

InitiatorPortNumber [in, optional]

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.

TargetPortal [in, optional]

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.

SecurityFlags [in, optional]

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:

ValueMeaning
ISCSI_SECURITY_FLAG_TUNNEL_MODE_PREFERRED

When set to 1, the initiator should make the connection in IPsec tunnel mode. Caller should set this flag or the ISCSI_SECURITY_FLAG_TRANSPORT_MODE_PREFERRED flag, but not both.

ISCSI_SECURITY_FLAG_TRANSPORT_MODE_PREFERRED

When set to 1, the initiator should make the connection in IPsec transport mode. Caller should set this flag or the ISCSI_SECURITY_FLAG_TUNNEL_MODE_PREFERRED flag, but not both.

ISCSI_SECURITY_FLAG_PFS_ENABLED

When set to 1, the initiator should make the connection with Perfect Forward Secrecy (PFS) mode enabled; otherwise, the initiator should make the connection with PFS mode disabled.

ISCSI_SECURITY_FLAG_AGGRESSIVE_MODE_ENABLED

When set to 1, the initiator should make the connection with aggressive mode enabled. Caller should set this flag or the ISCSI_SECURITY_FLAG_MAIN_MODE_ENABLED flag, but not both.

Note  The Microsoft software initiator driver does not support aggressive mode.

ISCSI_SECURITY_FLAG_MAIN_MODE_ENABLED

When set to 1, the initiator should make the connection with main mode enabled. Caller should set this flag or the ISCSI_SECURITY_FLAG_AGGRESSIVE_MODE_ENABLED flag, but not both.

ISCSI_SECURITY_FLAG_IKE_IPSEC_ENABLED

When set to 1, the initiator should make the connection with the IKE/IPsec protocol enabled; otherwise, the IKE/IPsec protocol is disabled.

ISCSI_SECURITY_FLAG_VALID

When set to 1, the other mask values are valid; otherwise, the iSCSI initiator service will use bitmap values that were previously defined for the target portal, or if none are available, the initiator service uses the default values defined in the registry.

 

Mappings [in, optional]

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.

LoginOptions [in, optional]

A pointer to a structure of type ISCSI_LOGIN_OPTIONS that contains the options that specify the characteristics of the login session.

KeySize [in, optional]

The size, in bytes, of the target's preshared key specified by the Key parameter.

Key [in, optional]

A preshared key to use when logging in to the target portal that exposes this target.

Note  If an IPsec policy is already associated with the target portal, the IPsec settings in this call are ignored.

IsPersistent [in]

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.

UniqueSessionId [out]

A pointer to a structure of type ISCSI_UNIQUE_SESSION_ID that, on return, contains a unique session identifier for the login session.

UniqueConnectionId [out]

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.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Iscsidsc.h

Library

Iscsidsc.lib

DLL

Iscsidsc.dll

Unicode and ANSI names

LoginIscsiTargetW (Unicode) and LoginIscsiTargetA (ANSI)

See also

ISCSI_LOGIN_OPTIONS
ISCSI_TARGET_PORTAL
ISCSI_UNIQUE_CONNECTION_ID
ISCSI_UNIQUE_SESSION_ID

 

 

Community Additions

ADD
Show:
© 2014 Microsoft