These webpages describe the Vternal Framework API, in Objective-C, Swift and Android/Java
iOS/Objective-C API
+ (void) registerApplicationWithKey:(NSString *)key
callback:(void(^)(BOOL))registered;
Description | Registers a Vternal Application, previously registered on the vternal.com website.Without a call to this API the VternalFramework is not activated and cannot be used. |
key | The key for this Bundle Id registered on the vternal.com website, Keys are a 64 character hexadecimal string. |
callback | Called when the attempt at registration is complete. Returns a Boolean value which tells the caller whether the registration was successful |
Example | [VternalFramework registerApplicationWithKey:@”<Vternal App Key>." callback:^(BOOL registered){ if( registered ) { NSLog(@"Registered for %@", [[NSBundle mainBundle] bundleIdentifier] ); } else { NSLog(@"Failed to register for %@", [[NSBundle mainBundle] bundleIdentifier] ); } }]; |
+ (BOOL) isInitialized;
Description | An indication of whether this App, has been successfully registered with the Vternal Network. |
returns | YES if the framework is registered for this App, otherwise NO; |
Example | BOOL registered = [VternalFramework isInitialized]; |
+ (NSString *) storeAssetToVternal:(NSData *)data;
Description | Stores data, not exceeding maxAssetSize (see below) bytes in The Vternal Network.. |
data | The data to be stored. This data is stored as a single asset in The Vternal Network, |
returns | If successful the Vternal Key of the new asset is returned. If the call was not successful, either because the data size exceeds maxAssetSize or because the App is not successfully registered with Vternal, nil is returned. You can distinguish between the two situations by calling [VternalFramework isInitialized]. |
Example | NSData *assetData …. NSString *newKey = [VternalFramework storeAssetToVternal:assetData]; |
+ (NSString *) storeUrlToVternal:(NSURL *)fileUrl;
Description | Stores a file, represented by a file URl (file://…) in The Vternal Network. If necessary a Vternal index asset is created. |
fileUrl | The accessible fileUrl of the file to be stored. If the file’s size is less than or equal to maxAssetSize it is stored as a single asset in The Vternal Network, If the filesize exceeds maxAssetSize then an index asset is created and the file is stored as multiple assets. |
returns | If successful the Vternal Key of the new asset is returned. If the file is bigger than maxAssetSize this is the key of a standard Vternal index asset. If the call was not successful, either because the file size exceeds maxFileSize, there is a file error, or because the App is not successfully registered with Vternal, nil is returned. You can distinguish between the two situations by calling [VternalFramework isInitialized]. |
Example | NSURL *fileUrl …. NSString *newKey = [VternalFramework storeUrlToVternal:fileUrl]]; |
+ VternalFindResult *fetchAssetFromVternal:(NSString *)key;
Description | Initiates and attempts to fetch a single Vternal Asset corresponding to the key specified. Repeated calls to this API with the same key allows the status of the background fetch to be monitored.Fetches may take several hours, of even days, to complete; although they typically take seconds or minutes. Developers should build their own infrastructure to call this APi periodically on outstanding fetches. If a request is not satisfied by the Vternal Network within 7 days a timeout is generated. |
key | A validly formatted (64 character hexadecimal string) key for the single asset to be fetched. Bogus keys return nil. |
return | A VternalFileResult object (see below) describing the status of the fetch. The VternalFileResult object describes the status of the fetch.The return is nil if the calling app is not registered, otherwise the ‘state’ field of the result indicates the status. It may be ‘FindingKeys’, ‘Done’, ‘“Timeout’ or ‘Error’. If it is ‘Done’ the assets has been found and the result describes the file containing it (the ‘filePath’ property contains the full pathname of the file containing the asset). In this case the ‘displayName’ property of the result is always set to @“asset”. If the state is “Error’ then the displayName property of the result may contain an error message. If the state is ‘Done’, It is the responsibility of the caller to delete any files after they have been processed. Failure to delete files can result in serious memory leaks. |
Example | NSString *key …. VternalFindResult *result = [VternalFramework fetchAssetFromVternal:key}];; |
+ VternalFindResult *fetchFileFromVternal:(NSString *key;
Description | Attempts to fetch the file corresponding to the key specified. If the file size exceeds one asset then the index is retrieved using ‘key’ and the other assets are retrieved and assembled into a file. This call returns the current status of the fetch and it is up to the caller to make this call repeatedly until the asset is found, there is a timeout or an error. The Framework initiates an attempt to find the asset on the network. Therefore repeated calls to this API with the same key allows the status of this background fetch to be monitored. Valid fetches either succeed, timeout (after 7 days) or result in an error. Fetches may take several hours, of even days, to complete; although they typically take seconds or minutes. |
key | A validly formatted (64 character hexadecimal string) key for the file to be fetched. Bogus keys simply timeout (after 7 days). |
return | A VternalFileResult object (see below) describing the status of the fetch. The VternalFileResult object describes the status of the fetch.The return is nil if the current App.is not registered, otherwise it always has a value. The state of the fetch is shown in the ‘state’ property of the result. It can take the values: ‘New’; ‘FindingKeys’ ; ‘Done’, in which case the ‘filePath’ and ‘displayName’ properties of the result are valid;‘Timeout’ or ‘Error’. If the state is ‘Error’ the ‘displayName’ property of the result contains an error message. If the state is ‘Done’, It is the responsibility of the caller to delete any files after they have been processed. Failure to delete files can result in serious memory leaks. |
Example | NSString *key …. VternalFindResult *result = [VternalFramework fetchAssetFromVternal:key]}; if( result ) { // result contains information about the status of the fetch. switch( result.state) { case Done: NSString *absolutePath = result.filePath; NSString *fileName = result.displayName; // do something with the file, then delete it. break;
case Timeout:: NSLog(@”Find of file for key %@ : timed out”, key); break; case Error:: NSLog(@”Find of file for key %@ : failed with error ‘%@’”, key, result.displayName); break; default:: NSLog(@”Find of file for key %@ : fetch state is ‘%@’”, key, result.state); break; } } else { // App is not registered …. } |
+ (VternalStatsResult *) getStatistics;
Description | Get statistics from this app’s Vternal Node. |
returns | A VternalStatsResult object which describes the status of the underlying Vternal Node. The data here is mostly for advanced users only. Returns nil if the App is not registered. The properties of the VternalStatsResult object are described below. |
Example | VternalStatsResult *stats = [VternalFramework getStatistics]; |
Properties of VternalStatsResult object | time_t configBirthday The UNIX time when this Node was first initialised. long configRealtimeElapsed The number of seconds that have elapsed since configBirthday time_t configLastConjugationTime The UNIX time of the last conjugation. time_t configAverageConjugationTime The average length in seconds of conjugations initiated by this node. time_t configAverageConjugationSpacing The average time in seconds between each conjugation long configNumberOfConjugations The total number of conjugations since birthDay long configNumberOfAssets The number of other people’s assets stored on this Node. long configStorageAllocated The amount, in bytes, of storage allocated for other people’s assetss on this Node. This is initially set to 1Gb.; long configStorageUsed The amount of storage, in bytes, currently used to store other’s assets. long configVternalizedBytes The number of bytes of data uploaded to The Vternal Network from this application. long configVternalizations The number of uploads that have been initiaited |
+ (long) setAllocation:(long)newSize;
Description | Set the amount of space allocated by this Vternal Node to store other people’s assets. The default is 1Gb. Use getStatistics to determine the current allocation. |
newSize | The new size to be allocated, in bytes. This number cannot be less than the storage used already( the value of which can be obtained using the getStatistics call). If an attempt is to set it lower than this the allocated space is set to the storage used and this value is returned to the caller. |
returns | The number of bytes now allocated on this Node for store other peoples’ Vternal assets.If the application is not registered, returns -1; |
Example | Long newAllocation = [VternalFramework setAllocation:newsize]; |
+ (long) maxAssetSize;
Description | The maximum size, in bytes, of a single asset, as supported by the Vternal Framework. The current default is 102400 bytes. |
returns | The maximum size, in bytes, of a single asset, as supported by the Vternal Framework. |
Example | long maximumAssetSize = [VternalFramework maxAssetSize]; |
+ (long) maxFileSize;
Description | The maximum file size, in bytes, as supported by the standard index of the Vternal Network. Currently this is 430Mb. |
returns | The maximum file size, in bytes, supported by the standard index of the Vternal Network. Currently this is 145Mb. For files bigger than this you must implement your own indexing scheme. |
Example | long maximumFileSize = [VternalFramework maxFileSize]; |
+ (int) conjugate;
Description | Causes the VternalFramework to talk to The Vternal Network and update its status by uploading any locally store assets, sending fetch information to the network and downloading any assets which the server offers it. This API is a synchronous call and should only be called from a background thread. It is normally called in application:performFetchWithCompletionHandler:completionHandler.Omitting a call to this function from ‘performFetchWithCompletionHandler’ will prevent the VF from functioning correctly. Conjugate is called whenever the caller wishes to advance the status of any outstanding fetches (see above). |
returns | The number of seconds the conjugation took. If the caller is not registered with the VF then -1 is returned.Note that if conjugate is called when the app. is in the background then the conjugation time is limited to, at most, 30s. |
Example | long timeConjugating = [VternalFramework conjugate]; |
IOS/Swift
func registerApplication(_ key: String,
_ callback: registered @escaping (Bool) -> Void)
Description | Registers a Vternal Application, previously registered on the vternal.com website. Without a call to this API the VternalFramework is not activated and cannot be used. |
key | The key for this Bundle Id registered on the vternal.com website, Keys are a 64 character hexadecimal string. |
callback | Called when the attempt at registration is complete. Returns a Boolean value which tells the caller whether the registration was successful |
Example | VternalFramework.registerApplication(withKey: "<Vternal Key>" , callback: {(result: Bool) -> () in if result { print("Registered for \(Bundle.main.bundleIdentifier!) "); } else { print("Failed to Register for \(Bundle.main.bundleIdentifier!) "); } }) |
func isInitialized() -> Bool
Description | An indication of whether this App, has been successfully registered with the Vternal Network. |
returns | YES if the framework is registered for this App, otherwise NO; |
Example | let registered = VternalFramework.isInitialized() |
func storeAssetToVternal(_ data: Data) -> String
Description | Stores data, not exceeding maxAssetSize (see below) bytes in The Vternal Network.. |
data | The data to be stored. This data is stored as a single asset in The Vternal Network, |
returns | If successful the Vternal Key of the new asset is returned. If the call was not successful, either because the data size exceeds maxAssetSize or because the App is not successfully registered with Vternal, nil is returned. You can distinguish between the two situations by calling VternalFramework.isInitialized(). |
Example | var Data assetData …. let newKey = VternalFramework.storeAssetToVternal(assetData) |
func storeUrlToVternal(_ fileUrl: URL) -> String
Description | Stores a file, represented by a file URl (file://…) in The Vternal Network. If necessary a Vternal index asset is created. |
fileUrl | The accessible fileUrl of the file to be stored. If the file’s size is less than or equal to maxAssetSize it is stored as a single asset in The Vternal Network, If the filesize exceeds maxAssetSize then an index asset is created and the file is stored as multiple assets. |
returns | If successful the Vternal Key of the new asset is returned. If the file is bigger than maxAssetSize this is the key of a standard Vternal index asset. If the call was not successful, either because the file size exceeds maxFileSize, there is a file error, or because the App is not successfully registered with Vternal, nil is returned. You can distinguish between the two situations by calling VternalFramework.isInitialized(). |
Example | var URL fileUrl …. let newKey = VternalFramework.storeUrlToVternal(fileUrl) |
func fetchAssetFromVternal(_ key: String) -> VternalFindResult
Description | Initiates and attempts to fetch a single Vternal Asset corresponding to the key specified. Repeated calls to this API with the same key allows the status of the background fetch to be monitored.Fetches may take several hours, of even days, to complete; although they typically take seconds or minutes. Developers should build their own infrastructure to call this APi periodically on outstanding fetches. If a request is not satisfied by the Vternal Network within 7 days a timeout is generated. |
key | A validly formatted (64 character hexadecimal string) key for the single asset to be fetched. Since the framework has no way of knowing if correctly formatted keys are really valid, bogus keys simply return nil. |
return | A VternalFileResult object (see below) describing the status of the fetch.. The VternalFileResult object describes the status of the fetch.The result is nil if the calling app is not registered, otherwise the ‘state’ field of the result indicates the status. It may be ‘FindingKeys’, ‘Done’, ‘“Timeout’ or ‘Error’. If it is ‘Done’ the assets has been found and the result describes the file containing it (the ‘filePath’ property contains the full pathname of the file containing the asset). In this case the ‘displayName’ property of the result is always set to @“asset”. If the state is “Error’ then the displayName property of the result may contain an error message. If the state is ‘Done’, It is the responsibility of the caller to delete any files after they have been processed. Failure to delete files can result in serious memory leaks. |
Example | let key …. let result = VternalFramework.fetchAssetFromVterna(key) if result { // result contains information about the status of the fetch. print(”aaset \(key) found at pathname \(result.filePath)”) } else { // the asset was not found. …. } |
func fetchFileFromVternal(_ key: String) -> VternalFindResult
Description | Attempts to fetch the file corresponding to the key specified. If the file size exceeds one asset then the index is retrieved using ‘key’ and the other assets are retrieved and assembled into a file. This call returns the current status of the fetch and it is up to the caller to make this call repeatedly until the asset is found, there is a timeout or an error. The Framework initiates an attempt to find the asset on the network. Therefore repeated calls to this API with the same key allows the status of this background fetch to be monitored. Valid fetches either succeed, timeout (after 7 days) or result in an error. Fetches may take several hours, of even days, to complete; although they typically take seconds or minutes. |
key | A validly formatted (64 character hexadecimal string) key for the single asset to be fetched. Since the framework has no way of knowing if the key is really used, bogus keys simply timeout (after 7 days). |
return | A VternalFileResult object (see below) describing the status of the fetch. The VternalFileResult object describes the status of the fetch.The result is nil if the current App.is not registered, otherwise it always has a value. The state of the fetch is shown in the ‘state’ property of the result. It can take the values: ‘New’; ‘FindingKeys’ ; ‘Done’, in which case the ‘filePath’ and ‘displayName’ properties of the result are valid;‘Timeout’ or ‘Error’. If the state is ‘Error’ the ‘displayName’ property of the result contains an error message. If the state is ‘Done’, It is the responsibility of the caller to delete any files after they have been processed. Failure to delete files can result in serious memory leaks. |
Example | let key …. let result = VternalFramework.fetchFileFromVternal( key.) if result { switch( result.state) { case Done: let absolutePath = result.filePath let fileName = result.displayName // do something with the file, then delete it. break;
case Timeout:: print(Find of file for key \(key) : timed out”) break; case Error:: print(”Find of file for key \(key) : failed with error ‘\(result.displayName)”) break; default:: print(”Find of file for key \(key) : fetch state is \(result.state)”) break; } } else { // the application is not registered …. } |
func getStatistics() -> VternalStatsResult
Description | Get statistics of this app’s Vternal Node. |
returns | A VternalStatsResult object which describes the status of the underlying Vternal Node. The data here is mostly for advanced users only. Returns nil if the App is not registered. The properties of the VternalStatsResult object are described below. |
Example | let stats = VternalFramework.getStatistics() |
Properties of VternalStatsResult structure | configBirthday The UNIX time when this Node was first initialised. configRealtimeElapsed The number of seconds that have elapsed since configBirthday configLastConjugationTime The UNIX time of the last conjugation. configAverageConjugationTime The average length in seconds of conjugations initiated by this node. configAverageConjugationSpacing The average time in seconds between each conjugation configNumberOfConjugations The total number of conjugations since birthDay configNumberOfAssets The number of other people’s assets stored on this Node. configStorageAllocated The amount, in bytes, of storage allocated for other people’s assetss on this Node. This is initially set to 1Gb.; configStorageUsed The amount of storage, in bytes, currently used to store other’s assets. configVternalizedBytes The number of bytes of data uploaded to The Vternal Network from this application. configVternalizations The number of uploads that have been initiaited |
func setAllocation(_ newSize: Int) -> Int
Description | Set the amount of space allocated by this Vternal Node to store other people’s assets. The default is 1Gb. Use getStatistics to determine the current allocation. |
newSize | The new size to be allocated, in bytes. This number cannot be less than the storage used already( the value of which can be obtained using the getStatistics call). If an attempt is to set it lower than this the allocated space is set to the storage used and this value is returned to the caller. |
returns | The number of bytes now allocated on this Node for store other peoples’ Vternal assets. If the application is not registered, returns -1; |
Example | let newAllocation = VternalFramework setAllocation:newsize]; |
func maxAssetSize() -> Int
Description | The maximum size, in bytes, of a single asset, as supported by the Vternal Framework. The current default is 102400 bytes. |
returns | The maximum size, in bytes, of a single asset, as supported by the Vternal Framework. |
Example | let maximumAssetSize = VternalFramework.maxAssetSize() |
func maxFileSize() -> Int
Description | The maximum file size, in bytes, as supported by the standard index of the Vternal Network. Currently this is 145Mb. For files bigger than this you must implement your own indexing scheme.. |
returns | The maximum file size, in bytes, supported by the standard index of the Vternal Network.. |
Example | let maximumFileSize = VternalFramework.maxFileSize() |
func conjugate(_ timeLimit: Int) -> Int
Description | Causes the VternalFramework to talk to The Vternal Network and update it status by uploading any locally store assets, sending fetch information to the network and downloading any assets which the server offers it. This API is normally called in application:performFetchWithCompletionHandler:completionHandler. Omitting a call to this function from ‘performFetchWithCompletionHandler’ will prevent the VF from functioning correctly. If ‘timeLimit’ is 0 the maximum allowed value (30s) is used. |
timeLimit | The maximum time allowed, in seconds, for the conjugation. The Apple documentation tells us that the maximum time an application can perform background tasks in application:performFetchWithCompletionHandler:completionHandler is 30 seconds. Therefore the sum of ‘timeLimit’ and any other time spent performing background fetch tasks cannot exceed this. Callers should adjust ‘timeLimit’ accordingly. |
returns | The number of seconds the conjugation took. If the caller is not registered with the VF then -1 is returned. |
Example | let timeConjugating = VternalFramework.conjugate(20) |
Android/Java
The VternalFramework API is slightly different between iOS and Android. Mainly because Android has a completely different way of handling background fetches. In the Android case a ‘Service’, which is entirely encapsulated within the VF, does the work and so it is not necessary to initiate ‘conjugation’ from within the host app.
Interfaces & Objects
A number of interfaces and objects are defined by the VF API. As follows:
Description | public class VternalFindResult { public enum FindState { New, FindingKeys, Error, Timeout, Done } public String filePath; public String displayName; public FindState state;; } |
Details | VternalFindResult class has three properties, as follows: filePath If the result.state is ‘Done’ this is the absolute pathname of the found asset or file, otherwise it is null. displayName If the result.state is ‘Done’ this is the name of the found file or asset. This always “asset” if the found object is a single asset. If the ‘state’ of the result is ‘Error’ then this field may contain an error message.Otherwise it is null. state One of the values ‘New’, ‘FindingKeys’, ‘Done’, ‘Timeout’, or ‘Error’.If the state is ‘Error’ the ‘displayName’ field may contain an error message. |
Description | public interface VternalRegister { void registered(boolean result); } The callback function ‘registered’ is called following a registerApplication operation. It returns a boolean (result) which indicates if the registration was successful. Subsequently, isInitialized() returns the value of this result. |
result | A boolean value indicating if the registration was successful or not. |
The Android API
These functions are all static functions of the class VternalFramework.
static public void registerApplication(final Activity activity, String apiKey, final VternalRegister callback );
Description | Registers a Vternal Application, previously registered on the vternal.com website. |
activity | The startup activity of the application, as specified in the manifest.Without a call to this API the VternalFramework is not activated and cannot be used. |
apiKey | The key for this Application Id/Package registered on the vternal.com website, Keys are a 64 character hexadecimal string. |
callback | The VternalRegister interface (see above) which contains the ‘registered’ implementation for the call. |
Example | VternalFramework.registerApplication(this, "<Vternal Key>", nee VternalRegister() { @Override public void registered(boolean result) { if( result ) { System.out.format(“successfully registered for %s\n” getPackageName() ); } else { System.out.format(“failed to register\n”) ); } } }); |
static public boolean isInitialized() ;
Description | An indication of whether this App, has been successfully registered with the Vternal Network. |
returns | ‘true’ if the framework is registered for this App, otherwise ‘false’; |
Example | boolean bRegistered = .VternalFramework.isInitialized(); |
static public void enterBackground();
Description | Informs The Vternal Framework that the app has entered the foreground.For simple apps this is normally put in the ‘onPause’ handler of the app’s activity. |
Example | @Override public void onPause() { super.onPause(); System.out.format("Vternal Direct : entering background\n");/ VternalFramework.enterBackground(); } |
static public void leaveBackground();
Description | Informs The Vternal Framework that the app has entered the foreground.For simple apps this is normally put in the ‘onResume’ handler of the app’s activity. |
Example | @Override public void onResume() { super.onResume(); System.out.format("Vternal Direct :leaving background\n");/ VternalFramework.leaveBackground(); } |
static public void conjugate();
Description | Cause The Vternal Framework to communicate with the network and update the status of any outstanding fetches. This API must be called periodically to advance any fetches. Periodically means typically every few minutes. Calling more often is unlikely to be effectual because it takes at least several minutes for the network to respond to submitted requests. |
Example | VternalFramework.conjugate(); |
public interface OnBackgroundConjugationHandler
{
void conjugated( Context context, boolean inBackground );
}
static public void setOnBackgroundConjugationHandler( OnBackgroundConjugationHandler handler );
Description | When the app is in the background the framework periodically calls the network (conjugates). Whenever it does so, it calls ‘handler’ when the background conjugation is complete. This allows apps to display and monitor fetch progress even when they are in a background. OnBackgroundConjugationHandler has one callback function ‘conjugated’. This has two parameters: ‘context’ which is the Android context in which the conjugation took place and ‘inBackground’, a boolean indicating whether the conjugation was in the background or not. Normally ‘inBackground’ is set to ‘true’. |
Example | VternalFramework.setOnBackgroundConjugationHandler( new VternalFramework.OnBackgroundConjugationHandler() { @Override public void conjugated(Context context, boolean inBackground ) { …. } }); |
static public String storeAssetToVternal(final byte[] asset );
Description | Stores data, not exceeding maxAssetSize (see below) bytes in The Vternal Network. |
asset | The data to be stored. This data is stored as a single asset in The Vternal Network, The size of the asset data cannot exceed maxAssetSize. |
return | The new Vternal Key for the asset stored, of null if the app is not registered of there is an error. |
Example | byte [] assetData …. String newKey = VternalFramework.storeAssetToVternal(assetData); |
static public String storeUriToVternal( final Uri contentUri );
Description | Stores a file, represented by a file URl (file://…) or an asset URI (content://…) returned, for example, by a Chooser) into The Vternal Network. If necessary a Vternal index asset is created. |
contentUrl | The contentUrl of the file to be stored. If the file’s size is less than or equal to maxAssetSize it is stored as a single asset in The Vternal Network, If the file’s size exceeds maxAssetSize, then an index asset is created and the file is stored as multiple assets. The total size of the file to be stored cannot exceed maxFileSize. If assets larger than maxFileSize are to be stored then it is up to the caller to implement their own indexing scheme. |
return | The new Vternal Key for the asset stored, of null if the app is not registered of there is an error. |
Example | final Uri uri = data.getData(); String newKay = VternalFramework.storeUriToVternal(uri); |
static public VternalFileResult fetchAssetFromVternal( final String key );
Description | Initiates and attempts to fetch a single Vternal Asset corresponding to the key specified. Repeated calls to this API with the same key allows the status of the background fetch to be monitored, but these calls must be preceded by a call to ‘conjugate() (see above) to advance the fetching process. Fetches may take several hours, of even days, to complete; although they typically take seconds or minutes. Developers should build their own infrastructure to call this APi periodically on outstanding fetches. If a request is not satisfied by the Vternal Network within 7 days a timeout is generated. |
key | A validly formatted (64 character hexadecimal string) key for the single asset to be fetched. Since the framework has no way of knowing if the key is really used, bogus keys simply return nil. |
return | A VternalFileResult object or null, if the app is unregistered or there is an error. The VternalFileResult object describes the status of the fetch.The result is null if the calling app is not registered, otherwise the ‘state’ field of the result indicates the status. It may be ‘FindingKeys’, ‘Done’, ‘“Timeout’ or ‘Error’. If it is ‘Done’ the assets has been found and the result describes the file containing it (the ‘filePath’ property contains the full pathname of the file containing the asset). In this case the ‘displayName’ property of the result is always set to “asset”. If the state is “Error’ then the displayName property of the result may contain an error message. If the state is ‘Done’, It is the responsibility of the caller to delete any files after they have been processed. Failure to delete files can result in serious memory leaks. |
Example | String key …. VternalFileResult result = VternalFramework.fetchAssetFromVternal( key ); |
static public VternalFileResult fetchFileFromVternal( final String key );
Description | Attempts to fetch the file corresponding to the key specified.This call returns the current status of the fetch and it is up to the caller to make this call repeatedly and precede each call to this API by a call to ‘conjugate()’ (see above), until the file is found, there is a timeout or an error. Fetches may take several hours, of even days, to complete; although they typically take seconds or minutes. Developers should build their own infrastructure to call this APi periodically on outstanding fetches. If a request is not satisfied by the Vternal Network within 7 days a timeout is generated. |
key | A validly formatted (64 character hexadecimal string) key for the single asset to be fetched. Since the framework has no way of knowing if the key is really used, bogus keys simply timeout (after 7 days). |
return | A VternalFileResult object or null if the app is unregistered or there is an error. The VternalFileResult object describes the status of the fetch.The result is null if the calling app is not registered, otherwise the ‘state’ field of the result indicates the status. It may be ‘FindingKeys’, ‘Done’, ‘“Timeout’ or ‘Error’. If it is ‘Done’ the assets has been found and the result describes the file containing it (the ‘filePath’ property contains the full pathname of the file containing the asset). In this case the ‘displayName’ property of the result is always set to the filename of the result. If the state is “Error’ then the displayName property of the result may contain an error message. If the state is ‘Done’, It is the responsibility of the caller to delete any files after they have been processed. Failure to delete files can result in memory leaks. |
Example | String key = …. VternalFileResult result = VternalFramework.fetchFileFromVternal(key); |
static public VternalStatistics getStatistics();
Description | Get statistics of this app’s Vternal Node. |
returns | A VternalStaitistics object which describes the latest status of the underlying Vternal Node. Returns null if the App is not registered. The properties of the VternalStatistics object are described below. |
Example |
VternalStatistics stats = VternalFramework.getStatistics(); |
Properties of VternalStatistics object | long configBirthday The UNIX time when this Node was first initialised. long configRealtimeElapsed The number of seconds that have elapsed since configBirthday long configLastConjugationTime The UNIX time of the last conjugation. long configAverageConjugationTime The average length in seconds of conjugations initiated by this node. long configAverageConjugationSpacing The average time in seconds between each conjugation long configNumberOfConjugations The total number of conjugations since birthDay long configNumberOfAssets The number of other people’s assets stored on this Node. long configStorageAllocated The amount, in bytes, of storage allocated for other people’s assetss on this Node. This is initially set to 1Gb.; long configStorageUsed The amount of storage, in bytes, currently used to store other’s assets. long configVternalizedBytes The number of bytes of data uploaded to The Vternal Network from this application. long configVternalizations The number of uploads that have been initiaited |
static public long setAllocation(final long newSize);
Description | Set the amount of space allocated by this Vternal Node to store other people’s assets. The default is 1Gb. Use getStatistics to determine the current allocation. |
newSize | The new size to be allocated, in bytes. This number cannot be less than the storage used already (as returned by a call to getStatistics() ). If an attempt is to set it lower than this the allocated space is set to the storage used and this value is returned to the caller. |
returns | The number of bytes now allocated on this Node for store other people’s Vternal assets. If the application is not registered or an error occurs, returns -1; |
Example | long newAllocation = VternalFramework.setAllocation(newsize); |
static public long maxAssetSize();
Description | The maximum size, in bytes, of a single asset, as supported by the Vternal Framework. The current default is 102400 bytes. |
returns | The maximum size, in bytes, of a single asset, as supported by the Vternal Framework. |
Example | long maximumAssetSize = VternalFramework.maxAssetSize(); |
static public long maxFileSize();
Description | The maximum file size, in bytes, as supported by the standard index of the Vternal Network. Currently this is 145Mb. For files bigger than this you must implement your own indexing scheme. |
returns | The maximum file size, in bytes, supported by the standard index of the Vternal Network.. |
Example | long maximumFiletSize = VternalFramework.maxFileSize(); |