Loading…

Kryptel/Java

IEncryptedDirectory interface

Declaration

package com.kryptel.storage;

public interface IEncryptedDirectory extends IFileSystemAttributes {
  IEncryptedDirectory[] GetDirectories() throws Exception;
  IEncryptedDirectory GetDirectory(String uniquePath, boolean bCreate) throws Exception;

  IEncryptedFile[] GetFiles() throws Exception;
  IEncryptedFile GetFile(String uniqueName, boolean bCreate) throws Exception;

  void Move(String name, IEncryptedDirectory dest) throws Exception;
  IFileSystemAttributes Delete(String name, boolean recursive) throws Exception;
  IFileSystemAttributes Undelete(String uniqueName, boolean recursive) throws Exception;

  void Decrypt(String targetDir,
               Object arg,
               IReplaceCallback replaceCallback,
               IProgressCallback progressFunc) throws Exception;

  void StartEncryptionBatch() throws Exception;
  void AddToEncryptionBatch(String path) throws Exception;
  void EncryptBatch(Object arg,
                    IReplaceCallback replaceCallback,
                    IProgressCallback progressFunc,
                    ICompressionLevelCallback comprLevel) throws Exception;

  void StartDecryptionBatch(String targetDir) throws Exception;
  void AddToDecryptionBatch(String uniquePath) throws Exception;
  void DecryptBatch(Object arg,
                    IReplaceCallback replaceCallback,
                    IProgressCallback progressFunc) throws Exception;
}

Description

This interface extends IFileSystemAttributes providing access to an encrypted directory.

GetDirectories

IEncryptedDirectory[] GetDirectories() throws Exception;

Returns an array of children directories. If the directory contains no children directories then the returned array is of zero length.

If storage control flag Constants.FSCF_ENUMS_RETURN_DELETED is set, the returned array will also include deleted directories (see IEncryptedFileStorage.SetStorageControlFlags).

GetDirectory

IEncryptedDirectory GetDirectory(String uniquePath, boolean bCreate) throws Exception;

Returns a child directory pointer, creating a new directory if necessary.

uniquePath
Unique path to a child directory. The specified path is relative to the current directory.
bCreate
If true and the requested directory does not exist, then create it (creating also all the intermediary directories if necessary). If false, return null.

GetFiles

IEncryptedFile[] GetFiles() throws Exception;

Returns an array of children files' IEncryptedFile pointers. If the directory contains no files then the returned array is of zero length.

If storage control flag Constants.FSCF_ENUMS_RETURN_DELETED is set, the returned array will also include deleted files (see IEncryptedFileStorage.SetStorageControlFlags).

GetFile

IEncryptedFile GetFile(String uniqueName, boolean bCreate) throws Exception;

Returns a child file's IEncryptedFile pointer, creating it if necessary.

uniqueName
The unique name of the file.
bCreate
If the file does not exist and this argument is true, then create it, otherwise return null.

Move

void Move(String name, IEncryptedDirectory dest) throws Exception;

Moves a children item to another directory.

name
The name of a child item (file or directory). The item must not be a deleted one.
dest
The destination directory to which the item is to be moved.

Delete

IFileSystemAttributes Delete(String name, boolean recursive) throws Exception;

Deletes the specified child item (file or directory), and returns the deleted item's IFileSystemAttributes. Depending on the EFFL_ITEM_IS_DIRECTORY flag the returned pointer may be cast to IEncryptedDirectory or IEncryptedFile.

If the storage does not keep deleted items (i.e the storage capabilities flag Constants.ESTOR_KEEPS_DELETED_OBJECTS is not set), then this function returns null.

name
The name of the child item (file or directory) that is to be deleted.
recursive
This parameter controls the function behavior if the item to be deleted is a non-empty directory. If true, then the directory and all its children items will be deleted. If false, the function will throw exception.
// This example deletes a directory if it is empty
IEncryptedDirectory dir = . . .     // Directory to be deleted
if ((dir.GetAttributes() &
     (EFFL_ITEM_CONTAINS_DIRECTORIES | EFFL_ITEM_CONTAINS_FILES)) == 0) {
  // Directory is empty
  dir.GetParent().Delete(dir.GetName(), false);
}

Note that you should check directory's attributes in order to determine if the directory is empty. Constructions like GetFiles().length == 0 should not be used for this purpose as the functions GetDirectories and GetFiles by default do not return deleted items. Even if both those functions return empty arrays, this does not mean that the directory is empty.

Undelete

IFileSystemAttributes Undelete(String uniqueName, boolean recursive) throws Exception;

Undeletes a previously deleted child item (file or directory), and returns its IFileSystemAttributes interface. Depending on the EFFL_ITEM_IS_DIRECTORY flag the returned pointer may be cast to IEncryptedDirectory or IEncryptedFile.

uniqueName
The unique name of the item to be undeleted. The function will throw an exception if the item is not deleted.
recursive
If true and the item is a directory, then the function also undeletes all the contained items (i.e. the whole subtree). If false, only the specified item will be undeleted; the children items, if any, will remain deleted. This argument is ignored if the item is a file.

Encryption

In order to encrypt files and/or folders and store them as children items of the current directory use the encryption batch functions.

  1. Call StartEncryptionBatch to start a new batch.
  2. Call AddToEncryptionBatch as many times as needed.
  3. Call EncryptBatch to finalize the batch and to perform actual encryption.

StartEncryptionBatch

void StartEncryptionBatch() throws Exception;

Starts a new encryption batch. This function must be called first.

AddToEncryptionBatch

void AddToEncryptionBatch(String path) throws Exception;

Add an item to the current encryption batch. The argument must be a valid path to an existing file or a directory. If the path points to a directory, the whole subtree will be encrypted.

EncryptBatch

void EncryptBatch(Object arg,
                  IReplaceCallback replaceCallback,
                  IProgressCallback progressFunc,
                  ICompressionLevelCallback comprLevel) throws Exception;

Finalize the batch and encrypt all the items in the batch adding them to the current storage directory.

Note that the source items do not get deleted or in any way changed during encryption. Encryption here means that an encrypted copy of the item is stored in the Kryptel container. Kryptel agents never delete user data; it is a responsibility of the client program.

arg
This argument is passed to the callback interfaces as is. The agent neither uses nor checks it. It usually refers to client-defined execution context and may be null if the callbacks are context-independent.
replaceCallback
Pointer to a class implementing IReplaceCallback. If null is specified, the function will quietly replace existing files (default behavior).
progressFunc
Pointer to a class implementing IProgressCallback (or, more likely, extending ProgressCallback class). Specify null if no progress bar is needed.
comprLevel
Pointer to a class implementing ICompressionLevelCallback interface. If specified, this callback will be called for every file in the batch. If null then Constants.DEFAULT_COMPRESSION_LEVEL will be set for all the files.

Decryption

There are two ways to decrypt data – using the Decrypt function, which decrypts the whole subtree, or using the decryption batch functions, which allow to decrypt children items selectively.

In order to perform batch decryption call the batch function as follows:

  1. Call StartDecryptionBatch to start a new batch.
  2. Call AddToDecryptionBatch as many times as needed.
  3. Call DecryptBatch to finalize the batch and to perform actual decryption.

Decrypt

void Decrypt(String targetDir,
             Object arg,
             IReplaceCallback replaceCallback,
             IProgressCallback progressFunc) throws Exception;

Decrypts the current directory and all the items it contains (i.e. the whole subtree).

targetDir
The target directory to which this directory is to be decrypted. If the agent is a File Agent, a valid directory must be specified. If the agent a a Backup Agent, a null or empty path is allowed; in this case the items will be restored to their original paths.
arg
This argument is passed to the callback interfaces as is. The agent neither uses nor checks it. It usually refers to client-defined execution context and may be null if the callbacks are context-independent.
replaceCallback
Pointer to a class implementing IReplaceCallback. If null is specified, the function will quietly replace existing files (default behavior).
progressFunc
Pointer to a class implementing IProgressCallback (or, more likely, extending ProgressCallback class). Specify null if no progress bar is needed.

StartDecryptionBatch

void StartDecryptionBatch(String targetDir) throws Exception;

Starts a new decryption batch. This function must be called first.

targetDir
The target directory to which the batch items are to be decrypted. If the agent is a File Agent, a valid directory must be specified. If the agent a a Backup Agent, a null or empty path is allowed; in this case the items will be restored to their original paths.

AddToDecryptionBatch

void AddToDecryptionBatch(String uniquePath) throws Exception;

Add a child item to the current decryption batch.

uniquePath
Unique path to the item, relative to the current directory. Note that it is a path, so it is possible to add not only immediate children.

DecryptBatch

void DecryptBatch(Object arg,
                  IReplaceCallback replaceCallback,
                  IProgressCallback progressFunc) throws Exception;

Finalize the batch and decrypt all the items to the directory specified in the preceding StartDecryptionBatch call.

arg
This argument is passed to the callback interfaces as is. The agent neither uses nor checks it. It usually refers to client-defined execution context and may be null if the callbacks are context-independent.
replaceCallback
Pointer to a class implementing IReplaceCallback. If null is specified, the function will quietly replace existing files (default behavior).
progressFunc
Pointer to a class implementing IProgressCallback (or, more likely, extending ProgressCallback class). Specify null if no progress bar is needed.