Table of Contents
As the hubiC client is just a headless service, it exposes an API to communicate with third party software. This API can be consumed with the widely used D-Bus IPC machanism.
The API is exposed on a session bus with com.hubiC
unique bus name. It is splitted over multiple objects.
The background synchronization process is registered as a D-Bus service so it should be started transparently when calling the API if it's not already running.
com.hubic.general — General API, always available
CurrentState readable s CurrentUploadSpeed readable x CurrentDownloadSpeed readable x LastMessages readable a(xiss)
Holds methods and properties that are not directly tied to a specific account. All methods and properties of this interface will be available at anytime.
This interface is exposed through the /com/hubic/General object.
Login (IN s email,
IN s password,
IN s synchronizedDir);
Connects to an existing account and starts synchronising given folder.
To connect without syncing, pass an empty string to synchronizedDir.
This method will not return until connection sequence has either finished successfully or failed (which can last up to 10 seconds).
IN s email:Account email address.
IN s password:Account password string.
IN s synchronizedDir:Directory to synchronize (absolute path).
Reconnect ();
If a connection has been already established, it can be resumed without passing credentials again with this method.
A possible use of this method is to retry connection if the automatic one failed for some reason (network not yet up, synchronized dir not yet mounted, ...) or if you called Logout() before.
Messages (i level,
s message,
s targetPath);
Messages emitted during synchronization to under exceptional circumstances.
Message levels are:
0: Information |
1: Warning |
2: Error |
3: Critical |
i level:Importance level. The higher it is, the more critical is the message.
s message:Message body. It is ready to be displayed to user and localized whenever possible.
s targetPath:Message target path. If message is about a particular file (for instance when a conflict occur), the path to the file will be provided. Otherwise this is an empty string.
StateChanged (s oldState,
s newState);
Fired when swtiching from one state to anther. See "CurrentState" for a list of possible states.
s oldState:The state before change.
s newState:The new state after the event.
CurrentState readable s
The current state of the client. Possible states are:
NotConnected: Client is not connected to an account |
Connecting: Connection is in progress |
Paused: Client is in pause, no synchronization will occur |
Idle: Connected, watching for changes and wait for next sync |
Busy: Connected and currently index/synchronize content |
CurrentUploadSpeed readable x
The current upload speed. It includes any utility requests that can be done by client such as listings, ...
CurrentDownloadSpeed readable x
The current download speed. It includes any utility requests that can be done by client such as listings, ...
LastMessages readable a(xiss)
History of 10 last "Messages" signals preceeded by a Unix timestamp.
com.hubic.account — Account dependant API.
Logout (); SynchronizeNow (); SetPauseState (IN b paused); Publish (IN s absolutePath); PublishWithDuration (IN s absolutePath, IN i duration); Unpublish (IN s absolutePath); GetPublishUrl (IN s absolutePath, OUT s ret); GetItemStatus (IN s absolutePath, OUT (sbb) ret); CreateBackup (IN s path, IN s name, IN s frequency, IN i versionsKept, IN b keepDeletedFiles);
QueueStatus readable (iiixx) RunningOperations readable a(xsssxx) PublishedFiles readable a(ssx) Account readable s SynchronizedDir readwrite s ExcludedFolders readwrite as TotalBytes readable x UsedBytes readable x
Holds methds and properties that are are linked to the current connected account (if any).
In NotConnected or Connecting states, methods usually raises an error if
they are called, properties returns a default value for Get opreation, Set
also results in error.
This interface is exposed through the /com/hubic/Account object.
Logout ();
Disconnect current account so you can call Login() or Reconnect() again.
SynchronizeNow ();
Triggers an immediate and complete synchronization cycle.
SetPauseState (IN b paused);
Change pause status. When enabling pause state, aborts any running operation. When resuming synchronization, makes a complete synchronization cycle.
See "CurrentState" and "StateChanged"
IN b paused:true to set account in Paused state, false to resume synchronization.
Publish (IN s absolutePath);
Publish a new file or folder. On failure, an error is raised and a message is sent over "Messages" explaining what went wrong.
IN s absolutePath:File to publish.
PublishWithDuration (IN s absolutePath,
IN i duration);
Publish a new file or folder. On failure, an error is raised and a message is sent over "Messages" explaining what went wrong.
In case of illegal TTL, just the error will be raised.
IN s absolutePath:File to publish.
IN i duration:Publication time to live (in days). Currently legal values are 1, 5, 10, 15, 20, 25, 30.
Unpublish (IN s absolutePath);
Deleted publication of a file. If the file were not published, this is a no-op.
IN s absolutePath:File to unpublish.
GetPublishUrl (IN s absolutePath,
OUT s ret);
Retrieves the URL of an already published file. If path was not published this result in an error.
IN s absolutePath:File to get the public URL.
OUT s ret:Public URL.
GetItemStatus (IN s absolutePath,
OUT (sbb) ret);
This method is intended to quickly gives the status of a particular file or folder. It notably used to draw the overlay icons on Windows and MacOSX.
This method does not raise error if it is called in NotConnected or
Connecting state.
The returned tuple is (in order):
Status (string)
The synchronization status. It can be Synchronized
(file is ok), Unsynchronized (the file is either
downloading or uploading), NoStatus (the file is
filtered out or outside of synchronized directory) or else
Error when an unexpected exception happen.
IsPublished (bool)Whether the item is published or not.
CanBePublished (bool)Whether the item could be published. It this is false, trying to Publish() the item will certainly fail.
IN s absolutePath:File to get the status from.
OUT (sbb) ret:A tuple containing the file status.
CreateBackup (IN s path,
IN s name,
IN s frequency,
IN i versionsKept,
IN b keepDeletedFiles);
This method creates a new backup, the created backup will be acessible through /com/hubib/Backup/<name> path.
This method may raise an error if the name or frequency are invalid, if the path cannot be accessed, ...
IN s path:Local folder to backup
IN s name:Backup name (must be a unique non empty string)
IN s frequency:Automatic backup frequency. Must be one of: "never", "hourly", "daily", "weekly" (case insensitive).
IN i versionsKept:Number of versions to keep (0: no versioning, negative: infinite versioning)
IN b keepDeletedFiles:whether or not the locally deleted files are also deleted on hubiC.
ItemChanged (s absolutePath);
Signal raised when a file or folder status changed somehow so GetItemStatus() should be called again to update file (e.g. change overlay icon, ...).
This signal can be raised in following cases:
| The item has been modified so it need to be synced, |
| The item synchronization operation(s) has been finished, |
| The item has been (un)published. |
s absolutePath:File or folder to update.
QueueStatus readable (iiixx)
Current status of synchronization queue. Gives how many items are
wating to be synchronized. This will be non-zero only in Busy state.
The tuple is (in order):
QueuedUploads (int)Number of queued upload operations.
QueuedDownloads (int)Number of queued download operations.
QueuedMisc (int)Number of other queued operation. This include deletes, copies, renames, ...
QueuedBytesToUpload (long)Amount of bytes to upload. Sum of sizes of QueuedUploads
QueuedBytesToDownload (long)Amount of bytes to download. Sum of sizes of QueuedDownloads
RunningOperations readable a(xsssxx)
List of currently running operations. It will be an empty list except
during Busy state.
The value is an array of tuples, themselves composed of (in order):
Id (int)Some unique operation id. Can be used to bind some progress indicator to the operation.
SourcePath (string)File on which operation work.
DestinationPath (string)Only used for copies and renames.
OperationType (string)Name of operation.
BytesDone (long)Current progress of operation (for Upload and Download),
or else -1 if operation does not have progress.
TotalBytes (long)Size of file to process (for Upload and Download),
or else -1 if operation does not have progress.
PublishedFiles readable a(ssx)
List of all published files. This list is cached locally and is updated time to time so it is fast to retrieve (but may not be up to date in some cases).
The value is an array of tuples, themselves composed of (in order):
Path (string)File on which operation work.
Url (string)The public HTTP link to see publication.
PublishedUntil (long)Date of the end of publication (Unix timestamp).
Account readable s
Account email address. Returns an empty string when no account is connected.
SynchronizedDir readwrite s
Currently synchronized directory. Can be changed at anytime (as long as account is connected). If operations were in progress, they are interrupted.
To disable synchronization, set the property to an empty string.
Returns an empty string when no account is connected or when synchronization is disabled.
ExcludedFolders readwrite as
Folders that will not be synchronized nor indexed. This is a collection of absolute paths, all of them must be inside "SynchronizedDir".
It can be changed at anytime (as long as account is connected). If operations were in progress, they are interrupted.
Returns an empty array when no account is connected.
com.hubic.settings
GetSetting (IN s setting, OUT s ret); SetSetting (IN s setting, IN s value); SetProxy (IN s hostname, IN i port); SetAuthenticatedProxy (IN s hostname, IN i port, IN s username, IN s password); UnsetProxy ();
TimeBetweenSynchronization readwrite u UseRecycleBin readwrite b AllowBugReporting readwrite b UploadSpeedLimit readwrite x DownloadSpeedLimit readwrite x ProxyEnabled readable b ProxyHost readable s ProxyPort readable i ProxyUsername readable s
GetSetting (IN s setting,
OUT s ret);
Retriees a setting value as string.
IN s setting:name of a property.
OUT s ret:setting value serialized as string.
SetSetting (IN s setting,
IN s value);
Set a setting value with a serialized string. As string serialization method is implementation defined, this method should be avoided.
IN s setting:name of a property.
IN s value:new setting value serialized as string.
SetProxy (IN s hostname,
IN i port);
Install a new unauthenticated proxy. Overwrites any previous proxy configuration.
IN s hostname:host name or IP address of the new proxy.
IN i port:port of the new proxy.
SetAuthenticatedProxy (IN s hostname,
IN i port,
IN s username,
IN s password);
Installs a new authenticated proxy. Overwrites any previous proxy configuration.
IN s hostname:host name or IP address of the new proxy.
IN i port:port of the new proxy.
IN s username:IN s password:TimeBetweenSynchronization readwrite u
Interval between two complete synchronization cycles in minutes. Note that local changes are detected immediately and trigger partial synchronizations independentely of this setting.
UseRecycleBin readwrite b
Whether locally deleted files are placed in recylce bin or deleted directly. Trash can is not yet implemented under Linux !
AllowBugReporting readwrite b
Whether automated bug reports are sent over unexpected errors.
UploadSpeedLimit readwrite x
Maximum upload speed in bytes per second (0 means unlimited).
DownloadSpeedLimit readwrite x
Maximum download speed in bytes per second (0 means unlimited).
com.hubic.backup — Controls backup state and settings.
BackupNow (); DownloadInto (IN s localPath); AttachToThisComputer (IN s localPath); Delete ();
Name readable s Owned readable b LastBackup readable x Size readable x LocalPath readwrite s BackupInProgress readable b Frequency readwrite s DeletePolicy readwrite s VersionsKept readwrite i
For each backup, an object of this interface is available under the path
/com/hubic/Backup/<name>.
Objects of this type does ont exists in NotConnected or Connecting
states.
Note that the backup are attached to only one client (see the man page for details). This is reflected by the com.hubic.backup::Owned attribute. Some operations are allowed only for owned backups (otherwise they would raise errors).
BackupNow ();
Triggers an immediate update of the backup. The backup needs to be owned.
DownloadInto (IN s localPath);
Triggers the download of the backup into given local folder. This method is asynchronous and return immediately.
IN s localPath:the local path to download into. Needs to be an empty folder.
LastBackup readable x
UNIX timestamp of the last full backup cycle. Can be -1 if the backup is in progress (this also include new backups).
Size readable x
Size of the backup in bytes. Note this does not reflect the size of the local folder, as versions are counted too and some data compression could occur.
LocalPath readwrite s
Local backup path. It can be changed to another folder, this will trigger an update.
Frequency readwrite s
The automatic backup frequency. This must br one of "never", "hourly", "daily", "weekly" (case insensitive).