From 3f6d00fb79ef77b53af2e686052acee14404c39c Mon Sep 17 00:00:00 2001 From: Alexander Ding Date: Wed, 19 Oct 2022 03:45:00 +0000 Subject: [PATCH] doc: document structs used in API group interfaces --- pkg/disk/types.go | 10 +++++++++- pkg/filesystem/types.go | 12 ++++++++---- pkg/iscsi/types.go | 3 +++ pkg/smb/types.go | 34 ++++++++++++++++++++++++++++----- pkg/system/types.go | 8 ++++++-- pkg/volume/types.go | 42 ++++++++++++++++++++++++++++++++++++----- 6 files changed, 92 insertions(+), 17 deletions(-) diff --git a/pkg/disk/types.go b/pkg/disk/types.go index c1c9b4db..e9bae221 100644 --- a/pkg/disk/types.go +++ b/pkg/disk/types.go @@ -8,6 +8,7 @@ type DiskLocation struct { } type ListDiskLocationsRequest struct { + // Intentionally empty } type ListDiskLocationsResponse struct { @@ -21,20 +22,26 @@ type PartitionDiskRequest struct { } type PartitionDiskResponse struct { + // Intentionally empty } type RescanRequest struct { + // Intentionally empty } type RescanResponse struct { + // Intentionally empty } type ListDiskIDsRequest struct { + // Intentionally empty } type DiskIDs struct { // Map of Disk ID types and Disk ID values - Page83 string + Page83 string + + // The disk serial number SerialNumber string } @@ -44,6 +51,7 @@ type ListDiskIDsResponse struct { } type GetDiskStatsRequest struct { + // Disk device number of the disk to get the stats from DiskNumber uint32 } diff --git a/pkg/filesystem/types.go b/pkg/filesystem/types.go index 1544afba..d1a0120f 100644 --- a/pkg/filesystem/types.go +++ b/pkg/filesystem/types.go @@ -1,24 +1,20 @@ package filesystem -// PathExistsRequest is the internal representation of requests to the PathExists endpoint. type PathExistsRequest struct { // The path whose existence we want to check in the host's filesystem Path string } -// PathExistsResponse is the internal representation of responses from the PathExists endpoint. type PathExistsResponse struct { // Indicates whether the path in PathExistsRequest exists in the host's filesystem Exists bool } -// PathValidRequest is the internal representation of requests to the PathValid endpoint. type PathValidRequest struct { // The path whose validity we want to check in the host's filesystem Path string } -// PathValidResponse is the internal representation of responses from the PathValid endpoint. type PathValidResponse struct { // Indicates whether the path in PathValidRequest is a valid path Valid bool @@ -47,6 +43,7 @@ type MkdirRequest struct { } type MkdirResponse struct { + // Intentionally empty } type RmdirRequest struct { @@ -66,11 +63,13 @@ type RmdirRequest struct { // Path cannot be a file of type symlink. // Maximum path length will be capped to 260 characters. Path string + // Force remove all contents under path (if any). Force bool } type RmdirResponse struct { + // Intentionally empty } type RmdirContentsRequest struct { @@ -93,6 +92,7 @@ type RmdirContentsRequest struct { } type RmdirContentsResponse struct { + // Intentionally empty } type CreateSymlinkRequest struct { @@ -111,6 +111,7 @@ type CreateSymlinkRequest struct { // source_path cannot already exist in the host filesystem. // Maximum path length will be capped to 260 characters. SourcePath string + // Target path is the location of the new directory entry to be created in the host's filesystem. // All special characters allowed by Windows in path names will be allowed // except for restrictions noted below. For details, please check: @@ -130,12 +131,15 @@ type CreateSymlinkRequest struct { } type CreateSymlinkResponse struct { + // Intentionally empty } type IsSymlinkRequest struct { + // The path whose existence as a symlink we want to check in the host's filesystem Path string } type IsSymlinkResponse struct { + // Indicates whether the path in IsSymlinkRequest is a symlink IsSymlink bool } diff --git a/pkg/iscsi/types.go b/pkg/iscsi/types.go index da32c524..75366856 100644 --- a/pkg/iscsi/types.go +++ b/pkg/iscsi/types.go @@ -75,6 +75,7 @@ type DiscoverTargetPortalResponse struct { type GetTargetDisksRequest struct { // Target portal whose disks will be queried TargetPortal *TargetPortal + // IQN of the iSCSI Target Iqn string } @@ -86,6 +87,7 @@ type GetTargetDisksResponse struct { } type ListTargetPortalsRequest struct { + // Intentionally empty } type ListTargetPortalsResponse struct { @@ -105,6 +107,7 @@ type RemoveTargetPortalResponse struct { type TargetPortal struct { // iSCSI Target (server) address TargetAddress string + // iSCSI Target port (default iSCSI port is 3260) TargetPort uint32 } diff --git a/pkg/smb/types.go b/pkg/smb/types.go index 318ee9c6..174a3d95 100644 --- a/pkg/smb/types.go +++ b/pkg/smb/types.go @@ -1,20 +1,44 @@ package smb type NewSMBGlobalMappingRequest struct { + // A remote SMB share to mount + // All unicode characters allowed in SMB server name specifications are + // permitted except for restrictions below + // + // Restrictions: + // SMB remote path specified in the format: \\server-name\sharename, \\server.fqdn\sharename or \\a.b.c.d\sharename + // If not an IP address, share name has to be a valid DNS name. + // UNC specifications to local paths or prefix: \\?\ is not allowed. + // Characters: + [ ] " / : ; | < > , ? * = $ are not allowed RemotePath string - LocalPath string - Username string - Password string + + // Optional local path to mount the SMB on + LocalPath string + + // Username credential associated with the share + Username string + + // Password credential associated with the share + Password string } type NewSMBGlobalMappingResponse struct { - // Intentionally empty. + // Intentionally empty } type RemoveSMBGlobalMappingRequest struct { + // A remote SMB share mapping to remove + // All unicode characters allowed in SMB server name specifications are + // permitted except for restrictions below + // + // Restrictions: + // SMB share specified in the format: \\server-name\sharename, \\server.fqdn\sharename or \\a.b.c.d\sharename + // If not an IP address, share name has to be a valid DNS name. + // UNC specifications to local paths or prefix: \\?\ is not allowed. + // Characters: + [ ] " / : ; | < > , ? * = $ are not allowed RemotePath string } type RemoveSMBGlobalMappingResponse struct { - // Intentionally empty. + // Intentionally empty } diff --git a/pkg/system/types.go b/pkg/system/types.go index e33ad859..9ff0756f 100644 --- a/pkg/system/types.go +++ b/pkg/system/types.go @@ -1,9 +1,11 @@ package system type GetBIOSSerialNumberRequest struct { + // Intentionally empty } type GetBIOSSerialNumberResponse struct { + // Serial number SerialNumber string } @@ -30,6 +32,7 @@ type StopServiceResponse struct { type ServiceStatus uint32 +// https://docs.microsoft.com/en-us/windows/win32/api/winsvc/ns-winsvc-service_status#members const ( SERVICE_STATUS_UNKNOWN ServiceStatus = iota SERVICE_STATUS_STOPPED @@ -43,6 +46,7 @@ const ( type Startype uint32 +// https://docs.microsoft.com/en-us/windows/win32/api/winsvc/nf-winsvc-changeserviceconfiga const ( START_TYPE_BOOT Startype = iota START_TYPE_SYSTEM @@ -60,9 +64,9 @@ type GetServiceResponse struct { // Service display name DisplayName string - // Service start type. + // Service start type // Used to control whether a service will start on boot, and if so on which - // boot phase. + // boot phase StartType Startype // Service status, e.g. stopped, running, paused diff --git a/pkg/volume/types.go b/pkg/volume/types.go index 5c6c4e8a..1754dd00 100644 --- a/pkg/volume/types.go +++ b/pkg/volume/types.go @@ -1,89 +1,121 @@ package volume type ListVolumesOnDiskRequest struct { - DiskNumber uint32 + // Disk device number of the disk to query for volumes + DiskNumber uint32 + + // The partition number (optional), by default it uses the first partition of the disk PartitionNumber uint32 } type ListVolumesOnDiskResponse struct { + // Volume device IDs of volumes on the specified disk VolumeIds []string } type MountVolumeRequest struct { - VolumeId string + // Volume device ID of the volume to mount + VolumeId string + + // Path in the host's file system where the volume needs to be mounted TargetPath string } type MountVolumeResponse struct { + // Intentionally empty } type IsVolumeFormattedRequest struct { + // Volume device ID of the volume to check VolumeId string } type IsVolumeFormattedResponse struct { + // Whether the volume is formatted with NTFS Formatted bool } type FormatVolumeRequest struct { + // Volume device ID of the volume to format VolumeId string } type FormatVolumeResponse struct { + // Intentionally empty } type WriteVolumeCacheRequest struct { + // Volume device ID of the volume to flush the cache VolumeId string } type WriteVolumeCacheResponse struct { + // Intentionally empty } type UnmountVolumeRequest struct { - VolumeId string + // Volume device ID of the volume to dismount + VolumeId string + + // Path where the volume has been mounted TargetPath string } type UnmountVolumeResponse struct { + // Intentionally empty } type ResizeVolumeRequest struct { - VolumeId string + // Volume device ID of the volume to resize + VolumeId string + + // New size in bytes of the volume SizeBytes int64 } type ResizeVolumeResponse struct { + // Intentionally empty } type GetVolumeStatsRequest struct { + // Volume device Id of the volume to get the stats for VolumeId string } type GetVolumeStatsResponse struct { + // Total bytes TotalBytes int64 - UsedBytes int64 + + // Used bytes + UsedBytes int64 } type GetDiskNumberFromVolumeIDRequest struct { + // Volume device ID of the volume to get the disk number for VolumeId string } type GetDiskNumberFromVolumeIDResponse struct { + // Corresponding disk number DiskNumber uint32 } type GetVolumeIDFromTargetPathRequest struct { + // The target path TargetPath string } type GetVolumeIDFromTargetPathResponse struct { + // The volume device ID VolumeId string } type GetClosestVolumeIDFromTargetPathRequest struct { + // The target path TargetPath string } type GetClosestVolumeIDFromTargetPathResponse struct { + // The volume device ID VolumeId string }