com.webos.service.filecache

API Summary

This service enables you to manage caching of files. It implements the global shared cache space, which webOS applications (such as Email) can use to temporary store cache files or send files to other webOS applications.

Overview of the API

(click to expand)

On the system level, the File Cache service is a daemon that starts after the webOS boots. It is responsible for caching filesystem requests, enabling to improve the performance of I/O operations and to save space on the the flash storage device.

You can configure the File Cache service behavior by calling its methods or by editing the options in the FileCache.conf file. In particular, you can:

  • specify the global shared cache space
  • configure space and object parameters
  • specify automatic expiration options or select to control expiration manually.

The default setting of the FileCache.conf file is:

  • totalCacheSpace 104857600 (100 MiB)

Open All


ChangeType

Description

Allows apps to modify the parameters of a cache type other than it’s name. You must specify the name of the cache type, and those cache type parameters that have to be modified. The cache type values are all as defined in DefineType.

Parameters

Name

Required

Type

Description

typeNameRequiredString

Name of cache type to be modified.

loWatermarkOptionalNumber

The minimum space in bytes guaranteed to be available for this cache type.

hiWatermarkOptionalNumber

The maximum space in bytes allowed to be used by this cache type.

sizeOptionalNumber

Default value in bytes for any object inserted into this cache type that does not specify a value for size. Size must not be negative.

costOptionalNumber

Default value between 0 and 100 for any object inserted into this cache type that does not specify a value for cost.

lifetimeOptionalNumber

Default value in seconds for any object inserted into this cache type that does not specify a value for lifetime. lifetime must not be negative.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-200"ChangeType: Invalid params: hiWatermark must be greater than loWatermark."

Parameters set are invalid

-196"ChangeType: Type 'test' does not exist."

Type is not yet defined

Example

Prerequisite: Invoke DefineType API to define the type name "test".

# luna-send -f -n 1 luna://com.webos.service.filecache/DefineType '{"typeName":"test", "size":1024, "loWatermark":102400, "hiWatermark":409600, "cost":5}'

Example:

# luna-send -f -n 1 luna://com.webos.service.filecache/ChangeType '{"typeName":"test", "size":2048, "cost":10}'


CopyCacheObject

Description

Enables copying of an object from the file cache to a non-cached location. On successful completion, newPathName will be returned as it may be different than expected due to filename collisions. If there is a name collision, the name will be made unique by adding a number to the file basename (i.e. foo.bar may become foo-(1).bar).

Parameters

Name

Required

Type

Description

pathNameRequiredString

The pathName ​is the path of the cache object to be copied

destinationOptionalString

The destination is the path to a target directory, this path will be validated to ensure you have write permissions to that directory.

fileNameOptionalString

The fileName is the name for the target file. If not passed, the fileName will be the value passed when calling InsertCacheObject.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
newPathNameOptionalString

On success, the newPathName will be returned. This file name may be different than expected due to filename collisions. If there is a name collision, the name will be made unique by adding a number to the file basename (i.e. foo.bar may become foo-(1).bar).

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-199"CopyCacheObject: Could not locate object"

Object does not exist.

-199"CopyCacheObject: pathName no longer found in cache."

Path not available anymore.

-199"CopyCacheObject: Invalid object id derived from pathname."

Invalid object ID.

-193"CopyCacheObject: Invalid destination, no write permission."

No write permission.

-192"CopyCacheObject: No fileName specified or found."

Invalid filename argument.

-192"CopyCacheObject: No unique destination name found."

Destination not found.

-192"CopyCacheObject: Invalid destination, not a directory."

Invalid destination path.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.filecache/CopyCacheObject '{"pathName":"/var/file-cache/test/M/OnRpQABl.bar", "destination":"", "fileName":"foo.bar"}'

 

Returns:

{
    "newPathName": "/media/internal/downloads/foo.bar",
    "returnValue": true
}


DefineType

Description

Defines a new cache type. This is intended for use by the backup service.

Optionally you may specify the default values for the size, cost, and lifetime. These defaults will be applied to all objects inserted into this cache type that do not specify their own values for these arguments. The size is in bytes, the cost is an integer between 0 and 100, and the lifetime is in seconds.  

The errorCode and errorText are only be returned if the returnValue is false.

Note: You can not define type with the same typeName. Use changeType to change an existing type.

Parameters

Name

Required

Type

Description

typeNameRequiredString

A typeName is a string up to 64 characters that uniquely identifies the new cache type. A typeName cannot start with a . ( the period character).

loWatermarkRequiredNumber

The minimum space in bytes guaranteed to be available for the cache type.

hiWatermarkRequiredNumber

The maximum space in bytes allowed to be used by the cache type.

sizeOptionalNumber

Default value in bytes for any object inserted into the cache type that does not specify a value for size.

costOptionalNumber

Default value between 0 and 100 for any object inserted into this cache type that does not specify a value for cost.

lifetimeOptionalNumber

Default value in seconds for any object inserted into this cache type that does not specify a value for lifetime.

dirTypeOptionalBoolean

Specifies whether the cache type should create directory entries. This is intended for use by the backup service.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-200"DefineType: Invalid params: hiWatermark must be greater than loWatermark."

Invalid parameters set.

-199"DefineType: Type 'test' already exists."

Typename already exists.

-197"DefineType: Failed to configure 'test'"

Type configuration failed.

-197"DefineType: Failed to allocate 'test'."

Type allocation failed.

-197"DefineType: Type 'test' already exists."

Type already exists.

-189"DefineType: Type 'test' has different configuration."

Configuration error.

Example

Example:

# luna-send -f -n 1 luna://com.webos.service.filecache/DefineType '{"typeName":"test","size":1024,"loWatermark":102400,"hiWatermark":409600,"cost":5}'


DeleteType

Description

Allows you to delete a previously defined cache type and frees up its space. All objects in the cache must be expired in order to delete a cache type. The app can call the ExpireCacheObject to force the objects to expire in the cache type. 

Parameters

Name

Required

Type

Description

typeNameRequiredString

The typeName is the name of the cache type to be deleted

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
freedSpaceOptionalNumber

Show the space freed by the cache being deleted on success.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-195"DeleteType: Type 'test' has subscribed objects."

Type has subscribed objects, hence, cannot be deleted.

-195"DeleteType: Type 'test' does not exist."

Type does not exist.

Example

Prerequisite: Invoke DefineType API to define the type name "test".

# luna-send -f -n 1 luna://com.webos.service.filecache/DefineType '{"typeName":"test", "size":1024, "loWatermark":102400, "hiWatermark":409600, "cost":5}'

Example:

# luna-send -n 1 -f luna://com.webos.service.filecache/DeleteType '{"typeName":"test"}'


DescribeType

Description

Returns cache type details. The DescribeType will return the currently assigned values for all cache type parameters. 

Note: Filesize as it resides on disk after accounting for the filesystem blocksize of 4096  loWatermark/hiWatermark will be padded with filesystem block size of 4096.

Parameters

Name

Required

Type

Description

typeNameRequiredString

The typeName is the name of the cache type for which more information about the cache type is needed.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
loWatermarkOptionalNumber

The minimum space in bytes guaranteed to be available for this cache type.

hiWatermarkOptionalNumber

The maximum space in bytes guaranteed to be available for this cache type.

sizeOptionalNumber

Default value in bytes for any object inserted into this cache type that does not specify a value for size.

costOptionalNumber

Default value between 0 and 100 for any object inserted into this cache type that does not specify a value for cost.

lifetimeOptionalNumber

Default value in seconds for any object inserted into this cache type that does not specify a value for lifetime.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-199"DescribeType: Type 'test' does not exists."

Type does not exist.

Example

Prerequisite: Invoke DefineType API to define the type name "test".

# luna-send -f -n 1 luna://com.webos.service.filecache/DefineType '{"typeName":"test", "size":1024, "loWatermark":102400, "hiWatermark":409600, "cost":5}'

Example:

# luna-send -f -n 1 luna://com.DescribeType.filecache/DescribeType '{"typeName":"test"}'

 

Returns:

{
    "size": 1024,
    "hiWatermark": 413696,
    "lifetime": 1,
    "loWatermark": 106496,
    "returnValue": true,
    "cost": 5
}


ExpireCacheObject

Description

Objects will normally be automatically expired form the cache as space is needed. If you want to force an item to be removed or if you want to remove items prior to calling DeleteType, you can expire an object manually.

The ExpireCacheObject method will not actually remove a subscribed object from the cache, but will mark the object for removal. The object is physically removed, when it has no active subscriptions.

NOTE: By default, objects in a cache type will be automatically expired from the cache as space is needed.

Parameters

Name

Required

Type

Description

pathNameRequiredString

Path of the object to be manually expired.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-199"ExpireCacheObject: pathName no longer found in cache."

Path not found.

-199"ExpireCacheObject: Invalid object id derived from pathname."

Invalid object ID.

-198"ExpireCacheObject: Expire deferred, object in use."

Object in use, cannot expire.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.filecache/ExpireCacheObject '{"pathName":"/var/file-cache/test/M/OnRpQABl.bar"}'

 

Returns:

{
    "returnValue": true
}


GetCacheObjectFilename

Description

Allows you to query the original filename of a particular object in a cache type.  In order to get the cache object file name the app must specify the path name of the object.  

Parameters

Name

Required

Type

Description

pathNameRequiredString

Path of the object for which the filename is to be queried.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
fileNameOptionalString

Original filename of the specified object if the call succeeds.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-199"GetCacheObjectFilename: Object '' doesn't exist"

Object path does not exist.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.filecache/GetCacheObjectFilename '{"pathName":"/var/file-cache/test/L/cvrKwABm.bar"}'

 

Returns:

{
    "fileName": "foo.bar",
    "returnValue": true
}


GetCacheObjectSize

Description

Allows you to query a particular object size in a cache type. In order to get the cache object size, the app must specify the pathname of the object. 

Parameters

Name

Required

Type

Description

pathNameRequiredString

Path for the cache object to be queried for its size.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
sizeOptionalNumber

Size of the specified object on success

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-199"GetCacheObjectSize: Object '' doesn't exist"

Object path does not exist.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.filecache/GetCacheObjectSize '{"pathName":"/var/file-cache/test/L/cvrKwABm.bar"}'

 

Returns:

{
    "returnValue": true,
    "size": 1024
}


GetCacheStatus

Description

Give status of the cache as a whole. The GetCacheStatus will return:

  • the number of cache types defined
  • the total space used by the objects in all cache types
  • the number of objects in all cache types
  • the available space in the cache

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Always returns true.

numTypesRequiredNumber

The number of cached types defined

sizeRequiredNumber

The total space used by the objects in all cache types

numObjsRequiredNumber

The number of objects in all cache types

availSpaceRequiredNumber

The available space in the cache

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.filecache/GetCacheStatus '{}'

 

Returns:

{
    "availSpace": 98304,
    "numObjs": 1,
    "numTypes": 1,
    "returnValue": true,
    "size": 8192
}


GetCacheTypes

Description

Returns an array of all defined cache types.

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Always returns true.

typesOptionalString array

Array of all defined cache types.

NOTE: If cache types are not defined, the “types” array is not returned.

Example

Prerequisite: Invoke DefineType API to define the type name "test".

# luna-send -f -n 1 luna://com.webos.service.filecache/DefineType '{"typeName":"test", "size":1024, "loWatermark":102400, "hiWatermark":409600, "cost":5}'

Example:

# luna-send -n 1 -f luna://com.webos.service.filecache/GetCacheTypes '{}'

 

Returns:

{
    "returnValue": true,
    "types": ["test"]
}


GetCacheTypeStatus

Description

Allows you to query the status of a particular cache type to obtain:

  • the total space used by the objects in the specified cache type
  • the number of objects in the specified cache type

Parameters

Name

Required

Type

Description

typeNameRequiredString

The name of the cache type for which the status information is to be retrieved.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
sizeOptionalNumber

The total space used by the objects in the specified cache type, if succeed

numObjsOptionalNumber

The number of objects in the specified cache type, if succeed.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-199"GetCacheTypeStatus: Type 'test' doesn't exist"

Type does not exist.

Example

Prerequisite:  

# luna-send -f -n 1 luna://com.webos.service.filecache/DefineType '{"typeName":"test", "size":1024, "loWatermark":102400, "hiWatermark":409600, "cost":5}'

Example:

# luna-send -n 1 -f luna://com.webos.service.filecache/GetCacheTypeStatus '{"typeName":"test"}'

 

Returns:

{
    "numObjs": 1,
    "returnValue": true,
    "size": 8192
}


GetVersion

Description

Returns the version of the File Cache API.

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
versionRequiredString

File Cache API version.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.filecache/GetVersion '{}'

 

Returns:

{
    "returnValue": true,
    "version": "1.1"
}


InsertCacheObject

Description

Inserts a new object of the specified type into the cache. The pathname parameter is required. It is stored with the object to ensure that the correct extension is provided, so that other module can choose a strategy to process this file (for example, choose the file viewer matching the extension).

Other parameters are optional. If not provided, the cache type default values defined are be used.

Returned is the path to the object in the cache. The subscribe setting should be set to true so that after the object is inserted you can write the file.

Parameters

Name

Required

Type

Description

typeNameRequiredString

The cache type of the object being inserted.

fileNameRequiredString

The filename is stored with the object and is used to ensure the correct extension is provided on the cache object. The filename will help any code, for example,  one that determines a file viewer, to operate correctly on a cached object file.

sizeOptionalNumber

The size is a value in bytes, should be greater than zero. Note that, size parameter is required, if type has no default size.

costOptionalNumber

The cost is a number between 1 and 100.

lifetimeOptionalNumber

The lifetime is value in seconds.

subscribeOptionalBoolean

Subscribe should be set to true so that after the object is inserted one can continues to make updates to the file.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
pathNameOptionalString

The path to the object in the cache is returned on success.

subscribedOptionalBoolean

Returns true if the subscription has been successful, returns false if it fails. May not be returned if subscribe was set to false in the arguments.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-200"InsertCacheObject: No type 'test' defined."

Type not defined.

-200"InsertCacheObject: Invalid params: size must be greater than 1 block when dirType = true."

Invalid parameters set.

-199"InsertCacheObject: Could not find '' bytes for object insert."

Size does not exist.

-199"InsertCacheObject: Type 'test' does not exist."

Type does not exist.

Example

Prerequisite: Invoke DefineType API to define the type name "test".

# luna-send -f -n 1 luna://com.webos.service.filecache/DefineType '{"typeName":"test", "size":1024, "loWatermark":102400, "hiWatermark":409600, "cost":5}'

Example:

# luna-send -n 1 -f luna://com.webos.service.filecache/InsertCacheObject '{"typeName":"test", "fileName":"foo.bar", "size":1024, "subscribe":false}'

 

Returns:

{
    "pathName": "/var/file-cache/test/M/OnRpQABl.bar",
    "returnValue": true
}


ResizeCacheObject

Description

By calling the ResizeCache you can specify the size of the cached object after it is inserted into the cache. Call this method if the final size of the object, which is being inserted into the cache, is not known by the moment, when you call the InsertCacheObject method. In this case:

  1. Call the InsertCacheObject method specifying the best approximate object size you can guess.
  2. Then call the ResizeCacheObject method on a subscribed object, if the the object size grows out of the previously specified size.

If the object is larger than the specified size when the write operation is complete, the object will be automatically removed from the cache. If the object is smaller than the specified size, the recorded object size will be adjusted to the correct size.

Remark: it is not a good practice to just specify a larger than expected size though as this could cause other objects to be expired from the cache to make room for the specified size.

Parameters

Name

Required

Type

Description

pathNameRequiredString

The path of the object to be resized.

newSizeRequiredNumber

The new size of the object in bytes.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
newSizeOptionalNumber

The new size of the resized object on success.

errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-199"ResizeCacheObject: pathName no longer found in cache."

Path not found.

-199"ResizeCacheObject: Invalid object id derived from pathname."

Invalid object ID.

-194"ResizeCacheObject: Unable to resize object."

Unable to resize object.

Example

Example:

# luna-send -f -n 1 luna://com.webos.service.filecache/ResizeCacheObject '{"newSize": 1024, "pathName": "/var/file-cache/test/H/LCWlwAJb.cat"}'

 

Returns:
{
    "newSize": 1024,
    "returnValue": true
}


SubscribeCacheObject

Description

Enables you to subscribe an object in the cache and hold a subscription to the object for the duration of your usage. An object cannot be expired from the cache while at least one subscription is active.

Parameters

Name

Required

Type

Description

pathNameRequiredString

The path for the object to be subscribed.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
subscribedRequiredBoolean

Indicates if subscribed to get notified.

  • true - Subscribed
  • false - Not subscribed
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-199"SubscribeCacheObject: "Invalid object id derived from pathname."

Invalid object ID.

-199"SubscribeCacheObject: No cache of type 'test' found for id ''."

Cache type not found.

-199"SubscribeCacheObject: Cache type not found for id ''."

Cache type not found.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.filecache/SubscribeCacheObject '{"pathName": "/var/file-cache/test/H/LCWlwAJb.cat"}'

 

Returns:

{
    "returnValue": true
}


TouchCacheObject

Description

Allows you to mark an object as recently used. This decreases the chances of the object from getting expired from the cache when the space is being reclaimed.

Parameters

Name

Required

Type

Description

pathNameRequiredString

path of the object to be marked as touched.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

-199"TouchCacheObject: Could not locate object"

Cache object not found.

-199"TouchCacheObject: pathName no longer found in cache."

Path not found.

-199"TouchCacheObject: Invalid object id derived from pathname."

Invalid object ID.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.filecache/TouchCacheObject '{"pathName":"/var/file-cache/test/D2_/aJQCH9.bar"}'

 

Returns:
{
    "returnValue": true
}


Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.