How to: MS iscsidsc lib usage

I recently start a small project about iSCSI volume management on windows platform. By using part of API  provided by Microsoft iscsidsc.dll(lib), I achieved base functions of an iSCSI initiator should do, like discovery target, session info, target info, persistent target management. During the research, coding and debugging, I think i should make this memo of those APIs, make them clear, especial usage.

All this APIs are the interface to the Microsoft iSCSI initiator service, user could use these API to customize APP, access service status.

  1. How to add a persistent target?
    1. A persistent target is written to MS registry, as mentioned in document, well, I did not check the location of registry, whatever, that is MS’s job and user could do nothing about that. To add a persistent target, login target using LoginIScsiTarget while IsPersistent set to TRUE. If there is already a session with IsPersistent login, this API may failed. So as to me, I logout all session before do this. The newly add persistent target will be showed in the list of “favorite targets” tab of MS iSCSI Initiator GUI. if IsPersistent is set to TRUE, the session_id of the login is somewhat special, session_id.AdapterSpecific is always zero, we could not using this session to do any more job. So logout the session ASAP. About API SetupPersistentIScsiDevices, I don’t know if it is necessary for the purple, MSDN did not mention it much.
  2. How to associate logic volume path with target?
    1. You can also use AddPersistentIScsiDevice, to add a logic volume path (eg. “x:\”) associate to that target, make target storage meaningful to general windows user. but the lib lack of API to find the connection between logic path/volume and physical drive/volume mapping. A target represent as a physical drive in windows platform, as far as I know, the only connection is the ISCSI_DEVICE_ON_SESSION.LegacyName, which we could retrieve by GetDevicesForIScsiSession, here are some way to connect to windows logic volume:
      1. Get the handle of device of LegacyName by CreateFile, then using DeviceIoControl with IOCTL_DISK_GET_DRIVE_LAYOUT_EX to get the drive layouts, also know as partitions, so we have all the GUID of all partition. Let’s name it GUID_LIST_1.
      2. Using FindFirstVolume/FindNextVolume/FindVolumeClose, we could enumerate all platform logic volume_name, whose pattern look like “\\?\Volume{GUID}\”, the GUID is the volume GUID assigned during partition creation, that is the identification of a GPT volume. Now we need to know the mapping of volume name and the logic volume number, or driver letter. Using  volume_name as parameter to GetVolumePathNamesForVolumeName, then we have driver letter, here we name it GUID_LIST_2. The following is quite straight, compare GUID_LIST_1 and GUID_LIST_2, we finally get a map of target and logic driver letter. You could find an example here.
  3. How to remove a persistent target?
    1. This sounds quite simple, just call RemoveIScsiPersistentTarget to accomplish the job. But when I try this, found that parameters of RemoveIScsiPersistentTarget must be accurate.

HRESULT WINAPI RemoveIscsiPersistentTarget(
_In_ PTCHAR InitiatorInstance,
_In_opt_ ULONG InitiatorPortNumber,
_In_ PTCHAR TargetName,

How could we get the accurate info for this API? The answer is: ReportIScsiPersistentLogins, which will get a list of PERSISTENT_ISCSI_LOGIN_INFO contain everything, check MSDN for detail.

I may add more subject to this article.





This entry was posted in tech and tagged . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s