Documents

Procedure ocp.documents.create(path)

Creates a new document from the provided dml code. The code must be in a directory called “Dml”, to which the path parameter points. Inside the drectory the main file must be called main.dml. Apart from that arbitrary named files are allowed to be in the folder and can be used in import statements from main.dml

Parameters

  • path (str) – Path to folder called dml which contains the docuemnt code

Return

  • docid (DocID) – The ID of the newly created document

Procedure ocp.documents.open(docid)

Opens the document with the given id. For this the node looks for peers that have it open already and connects to them. If no peers are found the opening fails. It then asks to join the document, which is accepted or denied by the other peers depending on your nodes authorisation status in the document. It hence is important to make sure your node is allowed to join.

Note

Only nodes that are already part of the document and have write permissions are allowed to add your node into the document configuration. One of these nodes needs to do so before “open” call will be successfull.

Parameters

  • docid (DocID) – The id of the document which should be opened

Procedure ocp.documents.close(docid)

Closes the document on the node and informs all other peers that we are leaving. Fails if the document is not open on the node.

Parameters

  • docid (DocID) – The id of the document which should be closed

Procedure ocp.documents.list()

Lists all currently open documents on the node.

Return

  • docs (list[DocID]) – All documents that are open

Procedure ocp.documents.invitations()

Lists all invitations, hence all documents we know of where we are allowed to join, but did not open it yet.

Return

  • docs (list[DocID]) – All documents we are invited in

Procedure ocp.documents.updateInvitations()

Searches the network for documents we are allowed to join, and republish a invitation event for each one found. Before the search however all known invitations are canceled by publishing an “invited” event with the uninvite arguments.

Event ocp.documents.created

Emitted when a new document was created on the node. This event is not received by the client calling the ocp.documents.create procedure, but by all other clients connected to the node.

Arguments

  • id (DocID) – The ID of the document that was created on the node

Event ocp.documents.opened

Emitted when a document was opened on the node. This event is not received by the client calling the ocp.documents.open procedure, but by all other clients connected to the node.

Arguments

  • id (DocID) – The ID of the document that was opened on the node

Event ocp.documents.closed

Emitted when a document was closed on the node. This event is not received by the client calling the ocp.documents.close procedure, but by all other clients connected to the node.

Arguments

  • id (DocID) – The ID of the document that was closed on the node

Event ocp.documents.invited

Emitted when our invitation status in any document changed. This happens if annother node adds our node to a documents configuration (invtation=True) or if we are removed from it (invitation=False). Once we received this invent with invitation=True we can call ocp.documents.open for this document.

Arguments

  • id (DocID) – The ID of the document in which our invitation status changed

  • invitation (bool) – True if we were invited, False if uninvited

Handling individual documents

Individual documents are accessed with their document ID simply by using the wamp procedure ocp.documents.*docid* . From there you have the change to manage the documents peers by adding, removing or changing their rigths. But you can also access all the content in that document, be it the RAW data you stored in it or the structured data according to your dml file.

Uri ocp.documents.docid.content.dmlpath.

Access anything within the document that is defined by the DML code. As the dml code builds up a hirarchical datastructure where each object has its own name, it can be easily be transformed into a WAMP uri. This is then used to access individual objects, properties or events. The end result of where the URI points to defines than the behaviour and how it should be used from the client:

  • Object: Calling the procedure returns the ObjID

  • Property: Calling the procedure without arguments returns the value, with an argument sets the property value

  • Event: Subscribing to the topic receives all event emits

  • Function: Calling the procedure calls the function and returns its results

Path

  • docid (DocID) – The document whichs content should be accessed

  • dmlpath (str) – Mutli state procedure to the dml object

Procedure ocp.documents.docid.execute(code)

Execute the provided javascript code in the document.

Path

  • docid (DocID) – The document in which the code shall be executed

Parameters

  • code (str) – JavaScript code that will be executed within the document

Return

Returns the outcome of the code

Procedure ocp.documents.docid.addPeer(peer, auth)

Adds new peer to the document

Path

  • docid (DocID) – ID of the document to add the peer to

Parameters

  • peer (NodeID) – Peer to add to the document

  • auth (str) – Authorisation of added peer

Procedure ocp.documents.docid.removePeer(peer)

Remove the peer from document

Path

  • docid (DocID) – ID of the document to add the peer to

Parameters

  • peer (NodeID) – Peer thats autorisation should change

Procedure ocp.documents.docid.listPeers(auth="None", joined=False)

List all peers in the document, possibly filtered auth or joined peers

Path

  • docid (DocID) – ID of the document to add the peer to

Procedure ocp.documents.docid.setPeerAuth(peer, auth)

Change the peer authorisation

Path

  • docid (DocID) – ID of the document to add the peer to

Parameters

  • peer (NodeID) – Peer thats autorisation should change

  • auth (str) – New authorisation

Procedure ocp.documents.docid.getPeerAuth(peer)

Read the peer authorisation

Path

  • docid (DocID) – ID of the document to add the peer to

Parameters

  • peer (NodeID) – Peer thats autorisation should change

  • auth (str) – New authorisation

Procedure ocp.documents.docid.hasMajority()

List all peers in the document, possibly filtered auth or joined peers

Path

  • docid (DocID) – ID of the document to add the peer to

Return

  • majority (bool) – True or false, dependent if majority is available

Procedure ocp.documents.docid.view(open)

List all peers in the document, possibly filtered auth or joined peers

Path

  • docid (DocID) – ID of the document to add the peer to

Return

  • open (bool) – True or false, dependent if majority is available

Event ocp.documents.docid.peerAdded(peer)
Event ocp.documents.docid.peerRemoved(peer)
Event ocp.documents.docid.peerAuthChanged(peer)
Event ocp.documents.docid.peerActivityChanged(peer)

Raw data handling

OCP documents support raw binary data as mass storage for complex and custom data. It can be added directly from the filesystem or as binary datastream with the provided procedures. If used the caller is responsible for storing the content identifiers in the document, it is not done automatically.

Procedure ocp.documents.docid.raw.CidByBinary(uri, arguments)

Adds raw binary data to the document. To support unlimited size data the binary stream is broken up in packages and a progressive WAMP procedure is used to deliver the packages. However, as only progressive read is supported, and not write, the user needs to provide a progressive wamp procedure the node can call. The arguments to CidByBinary are the URI of this procedure as well as any argument you want it to receive. The node than calls your procedure with those arguments and collects the binary data.

Path

  • docid (DocID) – ID of the document the data shall be added to

Parameters

  • uri (Uri) – The uri of the progressive WAMP procedure that delivers the binary data stream

  • arguments (any) – All arguments that shall be provided to the progressive procedure to identify the correct data

Return

  • cid (Cid) – Content identifier for the binary datastream

Procedure ocp.documents.docid.raw.BinaryByCid(uri, arguments)

Reads raw binary data from the document. To support unlimited size data the binary stream is broken up in packages, hence this is a progressive WAMP procedure. You need to collect all datapackages sent and combine them into the final binary data.

Path

  • docid (DocID) – ID of the document the data shall be added to

Parameters

  • uri (Uri) – The uri of the progressive WAMP procedure that delivers the binary data stream

  • arguments (any) – All arguments that shall be provided to the progressive procedure to identify the correct data

Return

  • cid (Cid) – Content identifier for the binary datastream

Procedure ocp.documents.docid.raw.CidByPath(path)

Reads raw data from the filesystem. It adds all the content in path to the document, including all subdirectories recursively. The returned cid will be valid for the full structure, all files and directories, and it is not possible to get a cid for individual files or subdirs. The structure stays intact, and when extracting the data again into a filesystem will be reproduced.

Note

The content in path is copied without any restrictions or filtering

Path

  • docid (DocID) – ID of the document the data in path shall be added to

Parameters

  • path (str) – Absolute filesystem path to file or directory

Return

  • cid (Cid) – Content identifier for the data in path

Procedure ocp.documents.docid.raw.PathByCid(cid, path)

Write data stored in the document into the given path. If the cid describes a binary stream or file, a file will be created, if it is a directory it will be recreated with the original structure. The name of files or toplevel directories are not stored and hence not recreated. The name will be the Cid. Use the return value to get the newly created path with full name.

Path

  • docid (DocID) – ID of the document the data in path shall be added to

Parameters

  • cid (Cid) – The content you want to store in the filesystem

  • path (str) – Absolute filesystem to directory to create the content in

Return

  • path (str) – Path of the newly created file or directory