Documentation ¶
Overview ¶
Package go_hidrive is a simple client SDK library for HiDrive cloud storage (mainly provided by [Strato](https://www.strato.de/cloud-speicher/) provider)
Currently, the following implementation are available: DirApi, FileApi and ShareApi.
All methods accept url.Values as a set of request parameters. You can also use Parameters objects to simplify parameters gathering required for request.
Example reading file from HiDrive:
import "golang.org/x/oauth2" func main() { oauth2config := oauth2.Config{ ClientID: "hi_drive_client_id", ClientSecret: "hi_drive_client_secret", Endpoint: oauth2.Endpoint{ AuthURL: StratoHiDriveAuthURL, TokenURL: StratoHiDriveTokenURL, AuthStyle: 0, }, Scopes: []string{"user", "rw"}, } token := &oauth2.Token{ RefreshToken: "hi_drive_oauth2_refresh_token", } client := oauth2config.Client(context.Background(), token) fileApi := NewFileApi(client, StratoHiDriveAPIV21) rdr, err := fileApi.GetFile(context.Background(), NewParameters().SetPath("/public/test_file.txt").Values) if err != nil { fmt.Println(err) return } contents, err := io.ReadAll(rdr) if err != nil { fmt.Println(err) return } fmt.Println(contents) }
Index ¶
- Constants
- Variables
- type Api
- type DirApi
- func (d DirApi) CreateDir(ctx context.Context, params url.Values) (*HiDriveObject, error)
- func (d DirApi) CreatePath(ctx context.Context, params url.Values) (*HiDriveObject, error)
- func (d DirApi) DeleteDir(ctx context.Context, params url.Values) error
- func (d DirApi) GetDir(ctx context.Context, params url.Values) (*HiDriveObject, error)
- type FileApi
- func (f FileApi) DeleteFile(ctx context.Context, params url.Values) error
- func (f FileApi) GetFile(ctx context.Context, params url.Values) (io.ReadCloser, error)
- func (f FileApi) UpdateFile(ctx context.Context, params url.Values, fileBody io.ReadCloser) (*HiDriveObject, error)
- func (f FileApi) UploadFile(ctx context.Context, params url.Values, fileBody io.ReadCloser) (*HiDriveObject, error)
- type HiDriveError
- type HiDriveObject
- type HiDriveShareInviteResponse
- type HiDriveShareInviteStatus
- type HiDriveShareObject
- type Parameters
- func (p *Parameters) SetDir(dir string) *Parameters
- func (p *Parameters) SetDirId(id string) *Parameters
- func (p *Parameters) SetFields(fields []string) *Parameters
- func (p *Parameters) SetFilePath(path string) *Parameters
- func (p *Parameters) SetId(id string) *Parameters
- func (p *Parameters) SetLimit(limit uint, offset uint) *Parameters
- func (p *Parameters) SetMTime(t time.Time) *Parameters
- func (p *Parameters) SetMaxCount(count int) *Parameters
- func (p *Parameters) SetMembers(members []string) *Parameters
- func (p *Parameters) SetMsg(msg string) *Parameters
- func (p *Parameters) SetName(name string) *Parameters
- func (p *Parameters) SetOnExist(onExists string) *Parameters
- func (p *Parameters) SetParentMTime(t time.Time) *Parameters
- func (p *Parameters) SetPassword(password string) *Parameters
- func (p *Parameters) SetPath(path string) *Parameters
- func (p *Parameters) SetPid(pid string) *Parameters
- func (p *Parameters) SetPwShareKey(key string) *Parameters
- func (p *Parameters) SetRecipient(recip string) *Parameters
- func (p *Parameters) SetRecursive(recursive bool) *Parameters
- func (p *Parameters) SetSalt(salt string) *Parameters
- func (p *Parameters) SetShareAccessKey(key string) *Parameters
- func (p *Parameters) SetSortBy(sortBy string) *Parameters
- func (p *Parameters) SetSortLang(lang string) *Parameters
- func (p *Parameters) SetTTL(ttl uint) *Parameters
- func (p *Parameters) SetWritable(writable bool) *Parameters
- type ShareApi
- func (s ShareApi) CreateShare(ctx context.Context, params url.Values) (*HiDriveShareObject, error)
- func (s ShareApi) DeleteShare(ctx context.Context, params url.Values) error
- func (s ShareApi) GetShare(ctx context.Context, params url.Values) (*HiDriveShareObject, error)
- func (s ShareApi) Invite(ctx context.Context, params url.Values) (*HiDriveShareInviteResponse, error)
- func (s ShareApi) UpdateShare(ctx context.Context, params url.Values) (*HiDriveShareObject, error)
- type Time
Constants ¶
const ( StratoHiDriveAPIV21 = "https://api.hidrive.strato.com/2.1" // Default HiDrive API endpoint StratoHiDriveAuthURL = "https://my.hidrive.com/client/authorize" // Default HiDrive authentication URL StratoHiDriveTokenURL = "https://my.hidrive.com/oauth2/token" // Default HiDrive token operations URL )
Variables ¶
var (
ErrShouldNotBeEmpty = errors.New("value should not be empty")
)
Functions ¶
This section is empty.
Types ¶
type Api ¶
Api - basic structure defining common logic for API interaction.
Property `HTTPClient` should be a http.Client type and retrieved from `oauth2` package, i.e. it should be pre-configured to perform OAuth2 authentication against HiDrive API before underlying method send any data.
Property `APIEndpoint` should be set to proper HiDrive API endpoint. Use NewApi function to create new instances of this type, it supports empty `endpoint` and injects default from StratoHiDriveAPIV21 constant.
type DirApi ¶
type DirApi struct {
Api
}
DirApi - structure represents a set of methods for interacting with HiDrive `/dir` API endpoint.
func NewDirApi ¶
NewDirApi - create new instance of DirApi.
Accepts http.Client and API endpoint as input parameters. If `endpoint` is empty string, then default StratoHiDriveAPIV21 value is used.
func (DirApi) CreateDir ¶
CreateDir - this method creates a new directory.
Provide a `path` and optional superior `pid` to create a new directory. Both, the `pid` and `path` parameters identify a filesystem object, at least one of them is always mandatory. It is allowed to use both together, in which case pid addresses a parent directory and the value of path is then considered relative to that directory.
Note: This will not create all missing parent directories - the parent directory within path has to exist! To create all missing parent directories in one shot use DirApi.CreatePath method.
Status codes:
- 201 - Created
- 400 - Bad Request (e.g. invalid parameter)
- 401 - Unauthorized (no authentication)
- 403 - Forbidden (wrong password)
- 404 - Not Found (e.g. ID not existing)
- 500 - Internal Error
Supported parameters:
- path (Parameters.SetPath)
- pid (Parameters.SetPid)
- on_exist (Parameters.SetOnExist)
- mtime (Parameters.SetMTime)
- parent_mtime (Parameters.SetParentMTime)
Returns HiDriveObject with information about the directory created.
func (DirApi) CreatePath ¶
CreatePath - this method performs the same action as DirApi.CreateDir and also creates all parent directories if they are missing.
Note: method does not support `pid` parameter, only `path` can be used
Returns HiDriveObject with information about the directory created.
func (DirApi) DeleteDir ¶
DeleteDir - this method deletes a given directory.
The optional parameter `recursive` determines, whether the operation shall fail on non-empty directories (which is also the default behavior), or continue deleting recursively all contents.
Both, the pid and path parameters identify a filesystem object, at least one of them is always mandatory. It is allowed to use both together, in which case pid addresses a parent directory and the value of path is then considered relative to that directory.
Enforce the HiDrive ACLs but adjusts deviant POSIX ACLs of the src and his parent when required. This may be necessary if the Permissions have been changed using protocols like SMB or rsync. The permissions will be restored if the operation completes successfully. Due to missing transactional semantics the permissions may not be restored if the operation fails (e.g. with an exception)
Status codes:
- 204 - No Content
- 400 - Bad Request (e.g. invalid parameter)
- 401 - Unauthorized
- 403 - Forbidden
- 404 - Not Found (e.g. ID not existing)
- 500 - Internal Error
Supported parameters:
- path (Parameters.SetPath)
- pid (Parameters.SetPid)
- recursive (Parameters.SetRecursive)
- parent_mtime (Parameters.SetParentMTime)
func (DirApi) GetDir ¶
GetDir - this method allows to query information about a given directory and all its contents.
In short; A few things to be aware of: - path and name values are returned as URL-encoded strings - an implicit limit of 5000 is used by default - this also works for snapshots
Usage details: Both, the pid and path parameters identify a filesystem object, at least one of them is always mandatory. It is allowed to use both together, in which case pid addresses a parent directory and the value of path is then considered relative to that directory.
Status codes:
- 200 - OK
- 400 - Bad Request (e.g. invalid parameter)
- 401 - Unauthorized (password required)
- 403 - Forbidden (wrong password)
- 404 - Not Found (ID does not exist or given path is not shared).
- 500 - Internal Error
Supported parameters:
- path (Parameters.SetPath)
- pid (Parameters.SetPid)
- members (Parameters.SetMembers)
- limit (Parameters.SetLimit)
- fields (Parameters.SetFields)
- sort (Parameters.SetSortBy)
- sort_lang (Parameters.SetSortLang)
Returns HiDriveObject with information about given directory.
type FileApi ¶
type FileApi struct {
Api
}
FileApi - structure represents a set of methods for interacting with HiDrive `/file` API endpoint.
func NewFileApi ¶
NewFileApi - create new instance of FileApi.
Accepts http.Client and API endpoint as input parameters. If `endpoint` is empty string, then default `StratoHiDriveAPIV21` value is used.
func (FileApi) DeleteFile ¶
DeleteFile - Delete a given file. Both, the pid and path parameters identify a filesystem object, at least one of them is always mandatory. It is allowed to use both together, in which case pid addresses a parent directory and the value of path is then considered relative to that directory. (<pid>/<path>)
Enforce the HiDrive ACLs but adjusts deviant POSIX ACLs of the src and his parent when required. This may be necessary if the Permissions have been changed using protocols like SMB or rsync. The permissions will be restored if the operation completes successfully. Due to missing transactional semantics the permissions may not be restored if the operation fails (e.g. with an exception)
Status codes:
- 204 - No Content
- 400 - Bad Request (e.g. invalid parameter)
- 401 - Unauthorized
- 403 - Forbidden
- 404 - Not Found (e.g. ID not existing)
- 500 - Internal Error
Supported parameters:
- path (Parameters.SetPath)
- pid (Parameters.SetPid)
- parent_mtime (Parameters.SetParentMTime)
func (FileApi) GetFile ¶
GetFile - This method retrieves a given file from the HiDrive.
Usage details: Both, the `pid` and `path` parameters identify a filesystem object, at least one of them is always mandatory. It is allowed to use both together, in which case pid addresses a parent directory and the value of path is then considered relative to that directory. (<pid>/<path>)
Status codes:
- 200 - OK
- 304 - Not Modified
- 400 - Bad Request (e.g. invalid parameter)
- 401 - Unauthorized (password required)
- 403 - Forbidden (wrong password)
- 404 - Not Found (ID does not exist or given path is not shared).
- 416 - Requested Range Not Satisfiable
- 500 - Internal Error
Supported parameters:
- path (Parameters.SetPath)
- pid (Parameters.SetPid)
Returns an io.ReadCloser object to read file contents using standard Go mechanisms.
func (FileApi) UpdateFile ¶ added in v0.2.2
func (f FileApi) UpdateFile(ctx context.Context, params url.Values, fileBody io.ReadCloser) (*HiDriveObject, error)
UpdateFile - Update a file by overwriting the target file with uploaded content. If the target file does not exist it will be created.
If you wish to create a file without overwriting data, use FileApi.UploadFile.
Usage Details:
The dir_id and dir parameters must be specified as query parameters of the URI. They refer to the file's target directory on the HiDrive storage, at least one of the parameters is mandatory. If both are given, dir_id addresses a directory and the value of dir is taken as a relative path to that directory.
The size of the request body to upload is limited to 2147483648 bytes (2G). The size of the complete request, including header, and after possible decoding of chunked encoding and decompression is limited to 3206545408 bytes (3058MB). Larger requests are rejected with 413 Request Entity Too Large.
As existence of the target file will be checked only after the upload is complete, the target file may have sprung into existence during the upload. To avoid losing the uploaded content in this case, the optional on_exist parameter can be set to "autoname". When set, the returned data will contain a name that differs from the provided name parameter.
Status codes:
- 201 - Created
- 400 - Bad Request (e.g. invalid parameter)
- 401 - Unauthorized (password required)
- 403 - Forbidden (wrong password)
- 404 - Not Found (ID does not exist or given path is not shared).
- 409 - Conflict
- 413 - Request Entity Too Large
- 415 - Unsupported Media Type
- 422 - Unprocessable Entity (e.g. name too long)
- 500 - Internal Error
- 507 - Insufficient Storage
Supported parameters:
- dir (Parameters.SetDir)
- dir_id (Parameters.SetDirId)
- name (Parameters.SetName)
- mtime (Parameters.SetMTime)
- parent_mtime (Parameters.SetParentMTime)
Returns HiDriveObject with information about uploaded file.
func (FileApi) UploadFile ¶
func (f FileApi) UploadFile(ctx context.Context, params url.Values, fileBody io.ReadCloser) (*HiDriveObject, error)
UploadFile -This method can be used to create a new file and store uploaded content.
Using POST guarantees that existing files will not be overwritten.
Usage Details:
The dir_id and dir parameters must be specified as query parameters of the URI. They refer to the file's target directory on the HiDrive storage, at least one of the parameters is mandatory. If both are given, dir_id addresses a directory and the value of dir is taken as a relative path to that directory.
The size of the request body to upload is limited to 2147483648 bytes (2G). The size of the complete request, including header, and after possible decoding of chunked encoding and decompression is limited to 3206545408 bytes (3058MB). Larger requests are rejected with 413 Request Entity Too Large.
As existence of the target file will be checked only after the upload is complete, the target file may have sprung into existence during the upload. To avoid losing the uploaded content in this case, the optional on_exist parameter can be set to "autoname". When set, the returned data will contain a name that differs from the provided name parameter.
Status codes:
- 201 - Created
- 400 - Bad Request (e.g. invalid parameter)
- 401 - Unauthorized (password required)
- 403 - Forbidden (wrong password)
- 404 - Not Found (ID does not exist or given path is not shared).
- 409 - Conflict
- 413 - Request Entity Too Large
- 415 - Unsupported Media Type
- 422 - Unprocessable Entity (e.g. name too long)
- 500 - Internal Error
- 507 - Insufficient Storage
Supported parameters:
- dir (Parameters.SetDir)
- dir_id (Parameters.SetDirId)
- name (Parameters.SetName)
- on_exist (Parameters.SetOnExist)
- mtime (Parameters.SetMTime)
- parent_mtime (Parameters.SetParentMTime)
Returns HiDriveObject with information about uploaded file.
type HiDriveError ¶
HiDriveError - represents HiDrive JSON-encoded errors.
Every time an API call receives non-OK code HiDrive also provides explanation in the response body. This response is converted into this type and returned as error on each method.
func (*HiDriveError) Error ¶
func (e *HiDriveError) Error() string
HiDriveError returns a string for the error and satisfies the error interface.
type HiDriveObject ¶
type HiDriveObject struct { Path string `json:"path"` Type string `json:"type"` ID string `json:"id"` ParentID string `json:"parent_id"` Name string `json:"name"` Size int64 `json:"size"` MemberCount int64 `json:"nmembers"` MTime Time `json:"mtime"` CTime Time `json:"ctime"` MetaHash string `json:"mhash"` MetaOnlyHash string `json:"mohash"` NHash string `json:"nhash"` CHash string `json:"chash"` Teamfolder bool `json:"teamfolder"` Readable bool `json:"readable"` Writable bool `json:"writable"` MIMEType string `json:"mime_type"` Members []*HiDriveObject `json:"members"` }
HiDriveObject represents HiDrive object - directory or file
func (*HiDriveObject) UnmarshalJSON ¶
func (h *HiDriveObject) UnmarshalJSON(b []byte) error
type HiDriveShareInviteResponse ¶ added in v0.2.0
type HiDriveShareInviteResponse struct {}
type HiDriveShareInviteStatus ¶ added in v0.2.0
type HiDriveShareInviteStatus struct {}
type HiDriveShareObject ¶
type HiDriveShareObject struct {}
HiDriveShareObject represents HiDrive Share object
func (*HiDriveShareObject) UnmarshalJSON ¶
func (s *HiDriveShareObject) UnmarshalJSON(b []byte) error
type Parameters ¶
func NewParameters ¶
func NewParameters() *Parameters
func (*Parameters) SetDir ¶
func (p *Parameters) SetDir(dir string) *Parameters
SetDir - adds "dir" parameter to the request - the path to the filesystem object (directory) to be used as the target for the upload operation.
The shortest possible path is "/" and it will always refer to the topmost directory accessible by the authenticated user. For a regular HiDrive user this is the HiDrive "root". If used with a share access_token it will be the shared directory.
This value must not contain path elements "." or ".." and must not end with a slash "/".
Note: if used in combination with a dir_id, this value is not allowed to start with "/" either.
Note: this is always a parent directory and must not contain the intended filename. Use the SetName method to specify the file name.
Can be used in the following methods:
func (*Parameters) SetDirId ¶
func (p *Parameters) SetDirId(id string) *Parameters
SetDirId - adds "dir_id" parameter to the request - the pulic id (pid) of the target filesystem object. (Or, if used in combination with dir, its parent directory.)
Note: a pid is not persistent upon changes (rename/move) to a filesystem object. So after this operation, the dir_id may no longer be valid. However, the current value will be part of the returned information (as parent_id) after a successful request.
Can be used in the following methods:
func (*Parameters) SetFields ¶
func (p *Parameters) SetFields(fields []string) *Parameters
SetFields - adds "fields" parameter to the query - list of value types that will be included in the response.
The performance of the call might be influenced by the amount of information requested. Therefore, it is recommended to use a "need to know" approach instead of "get all".
Can be used in the following methods:
- DirApi.GetFile
- ShareAPi.GetShare
Valid values for DirApi.GetDir:
- category - string - object category (audio, image, etc.)
- chash (*) - string - recursive hashvalue for the directory
- ctime - timestamp - ctime of the object
- has_dirs - bool - contains subdirs?
- id - string - path id (pid) of the directory
- members - array - include information on dir contents
- members.category - string - object category (audio, image, etc.)
- members.chash (*) - string - recursive hashvalue for a contained directory
- members.ctime - timestamp - ctime of contained objects
- members.has_dirs - bool - does a contained dir contain subdirs?
- members.id - string - path id (pid) of contained object
- members.image.exif - object - selected exif data of contained images
- members.image.height - int - height of contained images
- members.image.width - int - width of contained images
- members.mhash (*) - string - meta hash of contained objects
- members.mime_type - string - MIME type of contained files
- members.mohash (*) - string - meta only hash of contained objects
- members.mtime - timestamp - mtime of contained objects
- members.name - string - URL-Encoded name of contained objects
- members.nmembers (*) - int - number of members of a contained directory
- members.nhash (*) - string - name hash of contained objects
- members.path - string - URL-Encoded path of contained objects
- members.parent_id - string - path id (pid) of the members parent
- members.parent.id - string - path id (pid) of the members parent
- members.parent.writable - bool - write-permission of the members parent
- members.readable - bool - read-permission for contained objects
- members.rshare - array - sharing information (details below)
- members.size (*) - int - recursive size of a contained directory
- members.type - string - dir/file/symlink (see param "members")
- members.writable - bool - write-permission for contained objects
- members.shareable - bool - share-permission for the contained objects
- members.teamfolder - bool - indicates whether the contained object is a teamfolder or not
- mhash (*) - string - meta hash of the object
- mohash (*) - string - meta only hash of the object
- mtime - timestamp - mtime of the directory
- name - string - URL-Encoded name of the directory
- nhash (*) - string - name hash of the object
- nmembers - int - number of members in the directory
- parent_id - string - path id (pid) of the parent directory
- parent.id - string - path id (pid) of the parent directory
- parent.writable - bool - write-permission for the parent directory
- path - string - URL-Encoded path of the directory
- readable - bool - read-permission for the directory
- rshare - object - sharing information (details below)
- size (*) - int - recursive size of the directory
- type - string - dir/file/symlink (see param "members")
- writable - bool - write-permission for the directory
- shareable - bool - share-permission for the directory
- teamfolder - bool - indicates whether the directory is a teamfolder or not
Valid values for ShareApi.GetShare:
- count - int - the number of successfully completed downloads
- created - int - UNIX timestamp
- file_type - string - 'dir'
- has_password - bool
- is_encrypted - bool - is the given share encrypted
- id - string - the unique share id
- last_modified - int - UNIX timestamp
- maxcount (*) - int - maximum number of share-tokens
- name - int - name of the shared directory
- password (*) - string - optional password for the share
- path - string - path of the shared directory
- pid - string - path id of the shared directory
- readable - bool
- remaining - int - number of remaining available share tokens
- share_type - string - 'sharedir'
- size - int - size of the shared directory
- status - string - 'valid', 'invalid' or 'expired'
- ttl - int - time-to-live, in seconds, possibly negative
- uri - string - url of the shared directory
- valid_until - int - UNIX timestamp
- viewmode - string - single letter. influences the share folder display
- writable - bool
func (*Parameters) SetFilePath ¶
func (p *Parameters) SetFilePath(path string) *Parameters
SetFilePath - parses the path provided and uses the last part as file name (field "name"), the rest of the path is defined in the "dir" parameter.
Use this method to simplify settings upload path with a single string instead of calling two methods to set "dir" and "name separately.
Can be used in the following methods:
func (*Parameters) SetId ¶
func (p *Parameters) SetId(id string) *Parameters
SetId - adds "id" parameter to the request - a share id as returned by ShareApi.GetShare or ShareApi.CreateShare.
Can be used in the following methods:
func (*Parameters) SetLimit ¶
func (p *Parameters) SetLimit(limit uint, offset uint) *Parameters
SetLimit - adds "limit" parameter to the query - limit the number of directory entries returned, starting from an optional offset.
Both <limit> and <offset> need to be nonnegative integer values.
The returned amount of entries may be less than requested. To get all directory entries it is always recommended to check the nmembers field and issue another request with an <offset> updated accordingly.
A value of none or 0 for <limit> signifies to return as many entries as is feasible. This also works when combined with an offset.
Can be used in the following methods:
func (*Parameters) SetMTime ¶
func (p *Parameters) SetMTime(t time.Time) *Parameters
SetMTime - adds "mtime" parameter to the request - the modification time (mtime) of the file system target to be set after the operation.
Can be used in the following methods:
func (*Parameters) SetMaxCount ¶
func (p *Parameters) SetMaxCount(count int) *Parameters
SetMaxCount - adds "maxcount" parameter to the request - number of share tokens that can be issued for this share.
When not provided, the value will be set to unlimited, if the user's tariff supports it, otherwise to the maximum value permissible.
Can be used in the following methods:
func (*Parameters) SetMembers ¶
func (p *Parameters) SetMembers(members []string) *Parameters
SetMembers - adds "members" parameter to the query - list of directory content types to be included in the members part of the response
Valid values are:
- all - include all contents
- none - do not return any members
- dir - include sub-directories (not in combination with none or all)
- file - include files (not in combination with none or all)
- symlink - include symlinks (not in combination with none or all)
Can be used in the following methods:
func (*Parameters) SetMsg ¶ added in v0.2.0
func (p *Parameters) SetMsg(msg string) *Parameters
SetMsg - adds "msg" parameter to the request - A UTF-8 encoded message text that will be included in the e-mail.
Can be used in the following methods:
func (*Parameters) SetName ¶
func (p *Parameters) SetName(name string) *Parameters
SetName - adds "name" parameter to the request - the intended filename.
The name parameter is mandatory for binary uploads. It is forbidden for multipart/formdata uploads, where the name has to be specified as "filename" parameter within the content-disposition header.
Can be used in the following methods:
func (*Parameters) SetOnExist ¶
func (p *Parameters) SetOnExist(onExists string) *Parameters
SetOnExist - adds "on_exist" parameter to the request - Optional parameter to determine the API behavior in case of a conflict with an existing filesystem object.
Valid values are:
- "autoname" - find another name if the destination already exists
Can be used in the following methods:
func (*Parameters) SetParentMTime ¶
func (p *Parameters) SetParentMTime(t time.Time) *Parameters
SetParentMTime - adds "parent_mtime" parameter to the query - the modification time (mtime) of the file system target's parent folder to be set after the operation.
Can be used in the following methods:
func (*Parameters) SetPassword ¶
func (p *Parameters) SetPassword(password string) *Parameters
SetPassword - adds "password" parameter to the request - optional protection for the share.
Consider this recommended, especially the closer the share is set to the root directory. This parameter must be omitted for encrypted shares which require salt, share_access_key, pw_sharekey.
Can be used in the following methods:
func (*Parameters) SetPath ¶
func (p *Parameters) SetPath(path string) *Parameters
SetPath adds "path" parameter to the query - path to a filesystem object
Can be used in the following methods:
func (*Parameters) SetPid ¶
func (p *Parameters) SetPid(pid string) *Parameters
SetPid adds "pid" parameter to the query.
The public id is a path and encoding independent representation of a specific filesystem object. Also returned and referred to as id in data related responses.
Can be used in the following methods:
func (*Parameters) SetPwShareKey ¶
func (p *Parameters) SetPwShareKey(key string) *Parameters
SetPwShareKey - adds "pw_sharekey" parameter to the request - Password protected Share Key provided by the `hdcrypt` library for encrypted shares. Requires `password` to be absent and `salt` and `share_access_key` to be present.
Can be used in the following methods:
func (*Parameters) SetRecipient ¶ added in v0.2.0
func (p *Parameters) SetRecipient(recip string) *Parameters
SetRecipient - adds "recipient" parameter to the request - A RFC822-compliant, UTF-8 encoded e-mail address.
The parameter can be specified multiple times to send an invitation to more than one recipient at once.
Note: If the address is preceded by a string (e.g. "Bob Test" <bob@example.com>), the specified string is used as salutation in the generated mail without modification. It is recommended to specify names as "Firstname Lastname" instead of "Lastname, Firstname".
Can be used in the following methods:
func (*Parameters) SetRecursive ¶
func (p *Parameters) SetRecursive(recursive bool) *Parameters
SetRecursive - adds "recursive" parameter to the request - if `true`, the call will also delete non-empty directories and their contents recursively without throwing a 409 Conflict error.
Can be used in the following methods:
func (*Parameters) SetSalt ¶
func (p *Parameters) SetSalt(salt string) *Parameters
SetSalt - adds "salt" parameter to the request - Random salt value generated by the hdcrypt library for encrypted shares.
If this parameter is present, the share is created as 'encrypted' and share_access_key as well as pw_sharekey must also be present. The password parameter must be omitted because encrypted shares rely on a challenge-response authentication that only requires knowledge of the share_access_key.
Note: this attribute cannot be removed from a share.
Can be used in the following methods:
func (*Parameters) SetShareAccessKey ¶
func (p *Parameters) SetShareAccessKey(key string) *Parameters
SetShareAccessKey - adds "share_access_key" parameter to the request - Authentication key provided by the `hdcrypt` library for encrypted shares. Requires `password` to be absent and salt and `pw_sharekey` to be present.
Can be used in the following methods:
func (*Parameters) SetSortBy ¶
func (p *Parameters) SetSortBy(sortBy string) *Parameters
SetSortBy - adds "sort" parameter to the request - determines the order of the members in the result.
They can be sorted by name, category, mtime, type, or size. The default sort order is ascending. Prefix the sort criterion with a dash '-' for descending order. The first criteria in the comma-separated list take precedence over the others.
Names are sorted case-insensitive according to the locale determined by the sort_lang parameter. Numbers are compared by their numerical value.
The size of a directory is the recursive sum of file sizes of all files it contains. The size of a directory in a snapshot is sorted as 0 and not reported.
With the value "none" the output is unsorted.
Can be used in the following methods:
func (*Parameters) SetSortLang ¶
func (p *Parameters) SetSortLang(lang string) *Parameters
SetSortLang - adds "sort_lang" parameter to the request - Determines the locale used for sorting.
Currently allowed values are `de_DE`, `en_US` and `sv_SE`.
Can be used int the following methods:
func (*Parameters) SetTTL ¶
func (p *Parameters) SetTTL(ttl uint) *Parameters
SetTTL - adds "ttl" parameter to the request - share expiry.
A positive number defining seconds from now. Not specifying a value sets ttl to the tariff maximum.
Can be used in the following methods:
func (*Parameters) SetWritable ¶
func (p *Parameters) SetWritable(writable bool) *Parameters
SetWritable - adds "writable" parameter to the request - This option can be set to allow write access to the shared filesystem object.
Note: This includes deletion and modification of existing content.
Can be used in the following methods:
type ShareApi ¶
type ShareApi struct {
}ShareApi - structure represents a set of methods for interacting with HiDrive `/share` API endpoint.
func NewShareApi ¶
NewShareApi - create new instance of ShareApi.
Accepts http.Client and API endpoint as input parameters. If `endpoint` is empty string, then default `StratoHiDriveAPIV21` value is used.
func (ShareApi) CreateShare ¶
CreateShare - create a new share for a given directory anywhere inside your accessible HiDrive. You may limit the validity of a share to a given amount of time and protect it with a password.
Sharing a directory will allow anyone with knowledge of the specific (returned) share_id to access all data inside that directory and all its children (read-only by default).
The path of the shared directory including 'root/' must not exceed 1000 bytes.
For ease of access, HiDrive also provides a share-gui to access the shared files comfortably. The so-called "share_url" will be returned as well.
Status codes:
- 201 - Created
- 400 - Bad Request (e.g. invalid parameter)
- 401 - Unauthorized (no authentication)
- 403 - Forbidden (wrong password)
- 404 - Not Found (e.g. ID not existing)
- 500 - Internal Error
Supported parameters:
- maxcount (Parameters.SetMaxCount)
- path (Parameters.SetPath)
- pid (Parameters.SetPid)
- password (Parameters.SetPassword)
- writable (Parameters.SetWritable)
- ttl (Parameters.SetTTL)
- salt (Parameters.SetSalt)
- share_access_key (Parameters.SetShareAccessKey)
- pw_sharekey (Parameters.SetPwShareKey)
func (ShareApi) DeleteShare ¶
DeleteShare - delete a given share, thus invalidating each existing share `access_token` immediately.
Status codes:
- 204 - No Content
- 400 - Bad Request (e.g. invalid parameter)
- 401 - Unauthorized
- 403 - Forbidden
- 404 - Not Found (e.g. ID not existing)
- 500 - Internal Error
Supported parameters:
- id (Parameters.SetId)
func (ShareApi) GetShare ¶
GetShare - Get information about either one (given "id", "path" or "pid" parameter) or every existing share created by the authenticated user. You may customize the result set by adding optional "fields" values.
Status codes:
- 200 - OK
- 400 - Bad Request (e.g. invalid parameter)
- 401 - Unauthorized (password required)
- 403 - Forbidden (wrong password)
- 404 - Not Found (ID does not exist or given path is not shared).
- 500 - Internal Error
Supported parameters:
- id (Parameters.SetId)
- path (Parameters.SetPath)
- pid (Parameters.SetPid)
- fields (Parameters.SetFields)
func (ShareApi) Invite ¶ added in v0.2.0
func (s ShareApi) Invite(ctx context.Context, params url.Values) (*HiDriveShareInviteResponse, error)
Invite - Invite other people to a share via e-mail.
Status codes:
- 200 - OK
- 207 - Multi-Status (body contains multiple status messages)
- 400 - Bad Request (e.g. invalid parameter)
- 401 - Unauthorized (no authentication)
- 403 - Forbidden (wrong password)
- 404 - Not Found (e.g. ID not existing)
- 410 - Gone
- 500 - Internal Error
Supported parameters:
- id (Parameters.SetId)
- path (Parameters.SetPath)
- pid (Parameters.SetPid)
- fields (Parameters.SetFields)
Returns HiDriveShareInviteResponse object.
The returned object contains the keys `done` and `failed`. Each of these keys holds an array of objects describing successfully and unsuccessfully processed recipients. Each object holds at least the key `to`, which stores the recipient's e-mail address. Failure-objects contain an additional key `msg` which describes the encountered error. If all processed recipients share the same status code, the code will be returned as HTTP status code. Partial success or differing status codes are indicated by setting the HTTP status code to "207 Multi-Status". Failure- and done-objects will then contain the individual status of each processed recipient.
func (ShareApi) UpdateShare ¶
UpdateShare - update a given share. Change `ttl“, `maxcount` and add or remove a share password.
Note: It is not possible to change the target directory of an existing share! Please create a new one, if you wish to share another directory.
Status codes:
- 200 - OK
- 400 - Bad Request (e.g. invalid parameter)
- 401 - Unauthorized (no authentication)
- 403 - Forbidden (wrong password)
- 404 - Not Found (e.g. ID not existing)
- 500 - Internal Error
Supported parameters:
- id (Parameters.SetId)
- maxcount (Parameters.SetMaxCount)
- password (Parameters.SetPassword)
- writable (Parameters.SetWritable)
- ttl (Parameters.SetTTL)
- salt (Parameters.SetSalt)
- share_access_key (Parameters.SetShareAccessKey)
- pw_sharekey (Parameters.SetPwShareKey)
type Time ¶
Time represents date and time information for the API.
func (*Time) MarshalJSON ¶
MarshalJSON turns Time into JSON (in Unix-time/UTC).
func (*Time) UnmarshalJSON ¶
UnmarshalJSON turns JSON into Time.