Cinnamon Application Programming Interface (API)

NOTE: This documentation is under construction.

See Cinnamon API conceptual description for general information how to use the API.

Methods by name

attachlifecycle

changestate

connect

Parameters

Field	Value
command	connect
repository	Name of the repository.
user	User name.
password	User password.
machine	Machine name of the client machine.

Return value

The connect command returns an XML structure like this:

<connection>
  <ticket>319b75df-9840-4316-9647-f34625eb5515@content</ticket>
</connection>

The <ticket> element contains the session ticket the server has assigned. The client application must remember the ticket and use it as a parameter for all subsequent API calls, including disconnect.

Description

The connect command establishes a session with the server and returns the session ticket.

copy

copytoexisting

FIXME The documentation for the copytoexisting command is under construction.

Parameters

Field	Value
command	copytoexisting
sourceid	ID of the object whose content and / or metadata is to be copied.
targetid	ID of the target object to write the source data into. The target object can be any version of an existing object.
copymetasets	Comma separated list of metaset names that should be copied from source to target. The parameter is optional, if it is left out, no metasets will be copied.
copycontent	true to copy content, false to copy metasets only.
ticket	Session ticket.

Return value

The copytoexisting command returns an XML structure like this: TODO

<see_what_happens/>

TODO explain.

Description

The copytoexisting command copies content and / or metadata from the object specified by sourceid to an existing object specified by targetid. The boolean copycontent parameter controls whether the content should be copied or not. The optional copymetasets parameter controls the metasets to be copied, specified as a comma separated list of metaset names.

TODO is a lock required?

createlink

create

createfolder

createrelation

delete

deleteallversions

deletefolder

deletelink

deleterelation

detachlifecycle

disconnect

Parameters

Field	Value
command	disconnect
ticket	Session ticket to disconnect.

Return value

The disconnect command returns an XML structure like this:

<success>success.disconnect</success>

Description

The disconnect command ends an existing session, identified by its ticket.

echo

NOTE: echo has no legacy action.

getacls

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

getconfigentry

getcontent

Parameters

Field	Value
command	getcontent
id	ID of the object whose content is to be retrieved.
ticket	Session ticket to disconnect.

Return value

The getcontent command returns a stream with the content of the object. Typically, it is written to a file.

Description

The getcontent retrieves the content of an object identified by its id. getcontent is the only command returning file content instead of an XML structure.

getfolder

getfolderbypath

Parameters

Field	Value
command	getfolderbypath
path	Path to the folder.
include_summary	true returns summary with each object, false does not. The parameter can be omitted, the default is false.
ticket	Session ticket.

Return value

The getfolderbypath command returns an XML representation of the folder with the given path.

getfoldermeta

getfoldersbyid

getfoldertypes

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

getformats

getmeta

Parameters

Field	Value
command	getmeta
id	ID of the object whose metadata is to be retrieved.
ticket	Session ticket.

Return value

The getmeta command returns the metadata of the object with the specified id. getmeta does not support folders, use the getfoldermeta command instead, or retrieve a specific metaset with getmetaset (which also works for folders).

getmetaset

Parameters

Field	Value
command	getmetaset
id	ID of the object whose metadata is to be retrieved.
class_name	OSD (Object System Data) to retrieve an object metaset, Folder to retrieve a folder metaset.
type_name	Name of the metaset type to be retrieved.
ticket	Session ticket.

Return value

The getmetaset command returns one metaset of the metadata of the object or folder with the specified id.

getobject

getobjects

Parameters

Field	Value
command	getobjects
parentid	ID of the parent folder of the objects to be retrieved.
include_summary	true returns summary with each object, false does not. The parameter can be omitted, the default is false.
versions	all to return all versions, branch to return only the end nodes of branches, head to return only the latest versions of the returned objects.
ticket	Session ticket.

Return value

The getobjects command returns the objects inside the given parent folder as an XML representation.

getobjectsbyid

getobjtypes

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

getrelations

getrelationtypes

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

getsubfolders

Parameters

Field	Value
command	getsubfolders
parentid	ID of the parent folder of the subfolders to be retrieved. The value 0 returns the subfolders of the root folder.
include_summary	true returns summary with each object, false does not. The parameter can be omitted, the default is false.
ticket	Session ticket.

Return value

The getsubfolders command returns the subfolders inside the given parent folder as an XML representation.

getusers

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

getuserspermissions

listaclentries

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

listgroups

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

listindexgroups

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

listindexitems

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

listlanguages

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

listlifecycles

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

listmetasettypes

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

listuilanguages

NOTE: This API method will be replaced by a future, global session configuration transfer instead of individual methods.

lockobject

Parameters

Field	Value
command	lockobject
id	ID of the object to be locked.
ticket	Session ticket.

Return value

The lockobject returns <success/> or an <error/> element containing a message.

Description

The lockobject command places a write lock on the object identified by the id parameter.

renderindexedosd

NOTE: New in build 117.

renderindexedfolder

NOTE: New in build 117.

searchfolders

searchobjectids

searchobjects

Parameters

Field	Value
command	searchobjects
ticket	Session ticket.
query	Native Lucene XML query.
include_summary	true returns summary with each object, false does not. The parameter can be omitted, the default is false.
page_size	[optional] Maximal number of objects to returned.
page	[optional] Zero-based index of the page to return, this parameter may only be set if page_size has also been set.

Return value

The searchobjects command returns an XML structure like this:

<objects total-results="15">
  <object>
    <!-- XML representation of an object -->
  </object>
  <object>
    <!-- XML representation of an object -->
  </object>
  <!-- 13 more objects -->
</objects>

Description

The searchobjects command executes a search using a Lucene XML query and returns the objects found as an XML structure.

setchangedstatus

setcontent

Parameters

Field	Value
command	setcontent
id	ID of the object whose content is to be uploaded.
format	System name of the format whose content is to be uploaded.
ticket	Session ticket to disconnect.

Return value

The setcontent command command returns <success/> or an <error/> element containing a message.

Description

The setcontent command uploads content of the format identified by format to an existing object identified by its id. setcontent sends the file content stream to the server.

setmeta

setmetaset

setpassword

setsummary

setsysmeta

unlockobject

Parameters

Field	Value
command	unlockobject
id	ID of the object to be unlocked.
ticket	Session ticket.

Return value

The unlockobject command returns <success/> or an <error/> element containing a message.

Description

The unlockobject command removes a write lock on the object identified by the id parameter.

updatefolder

updatelink

version

Deprecated methods

checktranslation [deprecated]

IMPORTANT: This API method is deprecated and will be removed in a future release without further notice.

This method is highly special, can be replaced with other API methods and the render mechanism it supports is deprecated. Some customers still use it.

createtranslation [deprecated]

IMPORTANT: This API method is deprecated and will be removed in a future release without further notice.

This method is highly special, can be replaced with other API methods and the render mechanism it supports is deprecated. Some customers still use it.

forksession [deprecated]

IMPORTANT: This API method is deprecated and will be removed in a future release without further notice.

It is no longer used in client libraries and there seems to be no use case.

getsysmeta [deprecated]

IMPORTANT: This API method is deprecated and will be removed in a future release without further notice.

All such data is returned by getobject or other API methods returning objects.=== startrendertask [deprecated]

IMPORTANT: This API method is deprecated and will be removed in a future release without further notice.

This method is highly special, can be replaced with other API methods and the render mechanism it supports is deprecated. Some customers still use it.

sudo [deprecated]

IMPORTANT: This API method is deprecated and will be removed in a future release without further notice.

The entire sudo functionality has become obsolete with the change tracking logic.