go_hidrive

package module
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 21, 2023 License: Apache-2.0 Imports: 12 Imported by: 0

README

go-hidrive

Package go_hidrive is a simple client SDK library for HiDrive cloud storage (mainly provided by Strato provider) aimed to be used with Go (Golang).

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:

package main

import (
	"log"
	"context"
	"io"
	"fmt"

	"golang.org/x/oauth2"
	hidrive "github.com/Burmuley/go-hidrive"
)

func main() {
    oauth2config := oauth2.Config{
        ClientID:     "hi_drive_client_id",
        ClientSecret: "hi_drive_client_secret",
        Endpoint: oauth2.Endpoint{
            AuthURL:   hidrive.StratoHiDriveAuthURL,
            TokenURL:  hidrive.StratoHiDriveTokenURL,
            AuthStyle: 0,
        },
        Scopes: []string{"user", "rw"},
    }

    token := &oauth2.Token{
        RefreshToken: "hi_drive_oauth2_refresh_token",
    }

    client := oauth2config.Client(context.Background(), token)
    fileApi := hidrive.NewFile(client, hidrive.StratoHiDriveAPIV21)

    rdr, err := fileApi.Get(context.Background(), hidrive.NewParameters().SetPath("/public/test_file.txt").Values)

    if err != nil {
        log.Fatal(err)
    }

    contents, err := io.ReadAll(rdr)
    if err != nil {
        log.Fatal(err)
    }
	
    fmt.Println(contents)
}

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: Dir, File and Share.

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: 

package main

import (
	"log"
	"context"
	"io"
	"fmt"

	"golang.org/x/oauth2"
	hidrive "github.com/Burmuley/go-hidrive"
)

func main() {
	oauth2config := oauth2.Config{
		ClientID:     "hi_drive_client_id",
		ClientSecret: "hi_drive_client_secret",
		Endpoint: oauth2.Endpoint{
			AuthURL:   hidrive.StratoHiDriveAuthURL,
			TokenURL:  hidrive.StratoHiDriveTokenURL,
			AuthStyle: 0,
		},
		Scopes: []string{"user", "rw"},
	}

	token := &oauth2.Token{
		RefreshToken: "hi_drive_oauth2_refresh_token",
	}

	client := oauth2config.Client(context.Background(), token)
	fileApi := hidrive.NewFile(client, hidrive.StratoHiDriveAPIV21)

	rdr, err := fileApi.Get(context.Background(), hidrive.NewParameters().SetPath("/public/test_file.txt").Values)

	if err != nil {
		log.Fatal(err)
	}

	contents, err := io.ReadAll(rdr)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(contents)
}

Index

Constants

View Source 
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

View Source 
var (
	ErrShouldNotBeEmpty = errors.New("value should not be empty")
)

Functions

This section is empty.

Types

type Api 

type Api struct {
	APIEndpoint string
	HTTPClient  *http.Client
}

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.

func NewApi 

func NewApi(client *http.Client, endpoint string) Api

type Dir added in v0.3.0 

type Dir struct {
	Api
}

Dir - structure represents a set of methods for interacting with HiDrive `/dir` API endpoint.

func NewDir added in v0.3.0 

func NewDir(client *http.Client, endpoint string) Dir

NewDir - create new instance of Dir.

Accepts http.Client and API endpoint as input parameters. If `endpoint` is empty string, then default StratoHiDriveAPIV21 value is used.

func (Dir) Create added in v0.3.0 

func (d Dir) Create(ctx context.Context, params url.Values) (*Object, error)

Create - 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 Dir.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:

Returns Object with information about the directory created.

func (Dir) CreatePath added in v0.3.0 

func (d Dir) CreatePath(ctx context.Context, params url.Values) (*Object, error)

CreatePath - this method performs the same action as Dir.Create and also creates all parent directories if they are missing.

Note: method does not support `pid` parameter, only `path` can be used

Returns Object with information about the directory created.

func (Dir) Delete added in v0.3.0 

func (d Dir) Delete(ctx context.Context, params url.Values) error

Delete - 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:

func (Dir) Get added in v0.3.0 

func (d Dir) Get(ctx context.Context, params url.Values) (*Object, error)

Get - 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:

Returns Object with information about given directory.

type Error added in v0.3.0 

type Error struct {
	Code    json.Number `json:"code"`
	Message string      `json:"msg"`
}

Error - 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 (*Error) Error added in v0.3.0 

func (e *Error) Error() string

Error returns a string for the error and satisfies the error interface.

type File added in v0.3.0 

type File struct {
	Api
}

File - structure represents a set of methods for interacting with HiDrive `/file` API endpoint.

func NewFile added in v0.3.0 

func NewFile(client *http.Client, endpoint string) File

NewFile - create new instance of File.

Accepts http.Client and API endpoint as input parameters. If `endpoint` is empty string, then default `StratoHiDriveAPIV21` value is used.

func (File) Copy added in v0.3.2 

func (f File) Copy(ctx context.Context, params url.Values) (*Object, error)

Copy - copy a file.

The parameters `src` and `src_id` as well as `dst` and `dst_id` identify the source and destination for the operation. At least one source identifier and `dst` are always mandatory. It is allowed to use the related parameters together, in which case `src_id` and `dst_id` each address a parent directory and the values of `src` and `dst` are considered relative to that directory (e.g.<src_id>/<src>).

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).
  • 409 - Conflict
  • 422 - Unprocessable Entity (e.g. name too long)
  • 500 - Internal Error

Supported parameters:

  • src
  • src_id
  • dst
  • dst_id
  • on_exist (Parameters.SetOnExist) (possible values: `autoname`, `overwrite`)
  • dst_parent_mtime
  • preserve_mtime

func (File) Delete added in v0.3.0 

func (f File) Delete(ctx context.Context, params url.Values) error

Delete - 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:

func (File) Get added in v0.3.0 

func (f File) Get(ctx context.Context, params url.Values) (io.ReadCloser, error)

Get - 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:

Returns an io.ReadCloser object to read file contents using standard Go mechanisms.

func (File) Move added in v0.3.2 

func (f File) Move(ctx context.Context, params url.Values) (*Object, error)

Move - move a file.

The parameters `src` and `src_id` as well as `dst` and `dst_id` identify the source and destination for the operation. At least one source identifier and `dst` are always mandatory. It is allowed to use the related parameters together, in which case `src_id` and `dst_id` each address a parent directory and the values of `src` and `dst` are considered relative to that directory (e.g.<src_id>/<src>).

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).
  • 409 - Conflict
  • 422 - Unprocessable Entity (e.g. name too long)
  • 500 - Internal Error

Supported parameters:

  • src
  • src_id
  • dst
  • dst_id
  • on_exist (Parameters.SetOnExist) (possible values: `autoname`, `overwrite`)
  • src_parent_mtime
  • dst_parent_mtime

func (File) Rename added in v0.3.2 

func (f File) Rename(ctx context.Context, params url.Values) (*Object, error)

Rename - rename a 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>).

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
  • 422 - Unprocessable Entity (e.g. name too long)
  • 500 - Internal Error

Supported parameters:

func (File) Update added in v0.3.0 

func (f File) Update(ctx context.Context, params url.Values, fileBody io.ReadCloser) (*Object, error)

Update - 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 File.Upload.

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:

Returns Object with information about uploaded file.

func (File) Upload added in v0.3.0 

func (f File) Upload(ctx context.Context, params url.Values, fileBody io.ReadCloser) (*Object, error)

Upload -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:

Returns Object with information about uploaded file.

type Meta added in v0.3.0 

type Meta struct {
	Api
}

Meta - structure represents a set of methods for interacting with HiDrive `/meta` API endpoint.

func NewMeta added in v0.3.0 

func NewMeta(client *http.Client, endpoint string) Meta

NewMeta - create new instance of Meta.

Accepts http.Client and API endpoint as input parameters. If `endpoint` is empty string, then default `StratoHiDriveAPIV21` value is used.

func (Meta) Get added in v0.3.0 

func (m Meta) Get(ctx context.Context, params url.Values) (*Object, error)

Get - get metadata of a storage object (dir, file or symlink). At least one of the parameters path and pid is mandatory. If both are given, pid must address a directory and the value of path is a relative path from that directory.

To get data from a snapshot, the name of the snapshot must be provided in the snapshot parameter. The name must be UTF-8 encoded.

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:

func (Meta) Update added in v0.3.0 

func (m Meta) Update(ctx context.Context, params url.Values) (*Object, error)

Update - modify metadata of a file or directory.

At the moment `mtime` is the only attribute that can be changed. An attempt to modify metadata of a symlink causes 404 Not Found.

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:

type Object added in v0.3.0 

type Object 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"`
	Members      []*Object      `json:"members"`
	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"`
	Shareable    bool           `json:"shareable"`
	MIMEType     string         `json:"mime_type"`
	RShare       []*ShareObject `json:"rshare"`
}

Object represents HiDrive object - directory or file

func (*Object) UnmarshalJSON added in v0.3.0 

func (h *Object) UnmarshalJSON(b []byte) error

type Parameters 

type Parameters struct {
	url.Values
}

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) SetDst added in v0.3.2 

func (p *Parameters) SetDst(dst string) *Parameters

SetDst - adds "dst" parameter to the request - the path to the filesystem object to be used as the destination for the operation.

Example: /users/example/archive/something

Note: if used in combination with a dst_id, this value is not allowed to start with "/".

Can be used in the following methods:

func (*Parameters) SetDstId added in v0.3.2 

func (p *Parameters) SetDstId(dstId string) *Parameters

SetDstId - adds "dst_id" parameter to the request - if provided, this must always be the pid of a parent directory of the dst.

Example: b1489258310.123

Can be used in the following methods:

func (*Parameters) SetDstParentMTime added in v0.3.2 

func (p *Parameters) SetDstParentMTime(t time.Time) *Parameters

SetDstParentMTime - adds "dst_parent_mtime" parameter to the request - the modification time (mtime) of the destination parent folder to be set after the operation.

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:

Valid values for Dir.Get:

  • 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 Share.Get:

  • 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 Share.Get or Share.Create.

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) SetPreserveMTime added in v0.3.2 

func (p *Parameters) SetPreserveMTime(pmTime bool) *Parameters

SetPreserveMTime - adds "preserve_mtime" parameter to the request - the modification time (mtime) of the target will be copied from the source after the operation.

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) SetSrc added in v0.3.2 

func (p *Parameters) SetSrc(src string) *Parameters

SetSrc - adds "src" parameter to the request - the path to the filesystem object to be used as the source for the operation.

Example: /users/example/something

It is not allowed to use only "/" as a source, since it is the parent for all possible targets. Note: if used in combination with a src_id, this value is not allowed to start with "/" either.

Can be used in the following methods:

func (*Parameters) SetSrcId added in v0.3.2 

func (p *Parameters) SetSrcId(srcId string) *Parameters

SetSrcId - adds "src_id" parameter to the request - the public id (`pid`) of the source filesystem object (or when used in combination with src, its parent directory.)

Example: b1489258310.123

Note: a pid is not persistent upon changes (rename/move) to a filesystem object. So after this operation, the src_id may no longer be valid. However, the current value will be part of the returned information (as id) after a successful request.

Can be used in the following methods:

func (*Parameters) SetSrcParentMTime added in v0.3.2 

func (p *Parameters) SetSrcParentMTime(t time.Time) *Parameters

SetSrcParentMTime - adds "src_parent_mtime" parameter to the request - the modification time (mtime) of the source parent folder to be set after the operation.

Can be used in 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 Share added in v0.3.0 

type Share struct {
	Api
}

Share - structure represents a set of methods for interacting with HiDrive `/share` API endpoint.

func NewShare added in v0.3.0 

func NewShare(client *http.Client, endpoint string) Share

NewShare - create new instance of Share.

Accepts http.Client and API endpoint as input parameters. If `endpoint` is empty string, then default `StratoHiDriveAPIV21` value is used.

func (Share) Create added in v0.3.0 

func (s Share) Create(ctx context.Context, params url.Values) (*ShareObject, error)

Create - 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:

func (Share) Delete added in v0.3.0 

func (s Share) Delete(ctx context.Context, params url.Values) error

Delete - 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:

func (Share) Get added in v0.3.0 

func (s Share) Get(ctx context.Context, params url.Values) (*ShareObject, error)

Get - 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:

func (Share) Invite added in v0.3.0 

func (s Share) Invite(ctx context.Context, params url.Values) (*ShareInviteResponse, 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:

Returns ShareInviteResponse 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 (Share) Update added in v0.3.0 

func (s Share) Update(ctx context.Context, params url.Values) (*ShareObject, error)

Update - 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:

type ShareInviteResponse added in v0.3.0 

type ShareInviteResponse struct {
	Done   []ShareInviteStatus `json:"done"`
	Failed []ShareInviteStatus `json:"failed"`
}

type ShareInviteStatus added in v0.3.0 

type ShareInviteStatus struct {
	To      string `json:"to"`
	Code    int    `json:"code"`
	Message string `json:"msg"`
}

type ShareObject added in v0.3.0 

type ShareObject struct {
	ID           string `json:"id"`
	Path         string `json:"path"`
	Status       string `json:"status"`
	FileType     string `json:"file_type"`
	Count        int    `json:"count"`
	Created      Time   `json:"created"`
	HasPassword  bool   `json:"has_password"`
	Encrypted    bool   `json:"is_encrypted"`
	LastModified Time   `json:"last_modified"`
	MaxCount     int    `json:"maxcount"`
	Name         string `json:"name"`
	Password     string `json:"password"`
	PID          string `json:"pid"`
	Readable     bool   `json:"readable"`
	Remaining    int    `json:"remaining"`
	ShareType    string `json:"share_type"`
	Size         int    `json:"size"`
	TTL          int    `json:"ttl"`
	URI          string `json:"uri"`
	ValidUntil   Time   `json:"valid_until"`
	ViewMode     string `json:"viewmode"`
	Writable     bool   `json:"writable"`
}

ShareObject represents HiDrive Share object

func (*ShareObject) UnmarshalJSON added in v0.3.0 

func (s *ShareObject) UnmarshalJSON(b []byte) error
type Sharelink struct {
	Api
}

Sharelink - structure represents a set of methods for interacting with HiDrive `/sharelink` API endpoint. 

func NewSharelink(client *http.Client, endpoint string) Sharelink

NewSharelink - create new instance of Sharelink.

Accepts http.Client and API endpoint as input parameters. If `endpoint` is empty string, then default `StratoHiDriveAPIV21` value is used.

func (Sharelink) Create added in v0.3.1 

func (sl Sharelink) Create(ctx context.Context, params url.Values) (*ShareObject, error)

Create - create a new sharelink for a given file.

Both, the "pid" and "path" parameters refer to the file, at least one of them is mandatory. If both are given, `pid` addresses a parent directory, and the value of `path` is a relative path to the actual file.

Specific values might be limited by package-feature settings: Parameters `ttl` and `maxcount` are required, if the tariff defines a maximum limit for these values. The password protection feature is not available in all tariffs.

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:

func (Sharelink) Delete added in v0.3.1 

func (sl Sharelink) Delete(ctx context.Context, params url.Values) error

Delete - remove `sharelink`.

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:

func (Sharelink) Get added in v0.3.1 

func (sl Sharelink) Get(ctx context.Context, params url.Values) (*ShareObject, error)

Get - if no "id" parameter is given, a list of all sharelink objects of the user is returned. With a given "id" only the corresponding `sharelink` object is returned, if that exists.

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:

func (Sharelink) Update added in v0.3.1 

func (sl Sharelink) Update(ctx context.Context, params url.Values) (*ShareObject, error)

Update - update values for a given `sharelink` (not available for all tariffs).

Specific values might be limited due to package-feature settings:

  • The password protection feature is not available in all tariffs.
  • Parameters `ttl` and `maxcount` are required, if the tariff defines a maximum limit for these values.
  • The new value for `maxcount` must be equal to greater than the current count and the difference between the value of the current `maxcount` and the new `maxcount` may be limited, depending on the tariff.

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:

type Time 

type Time time.Time

Time represents date and time information for the API.

func (*Time) MarshalJSON 

func (t *Time) MarshalJSON() ([]byte, error)

MarshalJSON turns Time into JSON (in Unix-time/UTC).

func (*Time) UnmarshalJSON 

func (t *Time) UnmarshalJSON(data []byte) error

UnmarshalJSON turns JSON into Time.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.