-
Notifications
You must be signed in to change notification settings - Fork 3
/
AbstractHandle.html
1 lines (1 loc) · 21.6 KB
/
AbstractHandle.html
1
<!DOCTYPE html><html><head><title>AbstractHandle</title><link rel="stylesheet" href="KIDLspec.css"></head><body><div class="module"><div class="comment"><div>/*</div><div><span class="space"></span><span>*</span><span class="space"></span><span>A KBase module: AbstractHandle</span></div><div><span class="space"></span><span>*</span><span class="space"></span><span><span class="space"></span><span class="space"></span>provides a programmatic access to a remote file store</span></div><div><span class="space"></span><span>*/</span></div></div><span class="keyword">module</span><span class="space"></span><span class="name">AbstractHandle</span><span class="space"></span><span>{</span><br><br><div><span class="typedef"><div class="comment"><div><span class="tab"></span><span>/*</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>Handle provides a unique reference that enables</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>access to the data files through functions</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>provided as part of the HandleService. In the case of using</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>shock, the id is the node id. In the case of using</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>shock the value of type is shock. In the future</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>these values should enumerated. The value of url is</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>the http address of the shock server, including the</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>protocol (http or https) and if necessary the port.</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>The values of remote_md5 and remote_sha1 are those</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>computed on the file in the remote data store. These</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>can be used to verify uploads and downloads.</span></div><div><span class="tab"></span><span class="space"></span><span>*/</span></div></div><span class="tab"></span><span class="keyword">typedef</span><span class="space"></span><span class="primitive">string</span><span class="space"></span><span class="name" id="typedefAbstractHandle.HandleId">HandleId</span><span>;</span></span></div><br><div><span class="typedef"><div class="comment"></div><span class="tab"></span><span class="keyword">typedef</span><span class="space"></span><span class="primitive">string</span><span class="space"></span><span class="name" id="typedefAbstractHandle.NodeId">NodeId</span><span>;</span></span></div><br><div><span class="typedef"><div class="comment"></div><span class="tab"></span><span class="keyword">typedef</span><span class="space"></span><span><span class="primitive">structure</span><span class="space"></span><span>{</span><div><span><span class="tab"></span><span class="tab"></span><span class="name"><a href="#typedefAbstractHandle.HandleId">HandleId</a></span><span class="space"></span><span class="name">hid</span><span>;</span></span></div><div><span><span class="tab"></span><span class="tab"></span><span class="primitive">string</span><span class="space"></span><span class="name">file_name</span><span>;</span></span></div><div><span><span class="tab"></span><span class="tab"></span><span class="name"><a href="#typedefAbstractHandle.NodeId">NodeId</a></span><span class="space"></span><span class="name">id</span><span>;</span></span></div><div><span><span class="tab"></span><span class="tab"></span><span class="primitive">string</span><span class="space"></span><span class="name">type</span><span>;</span></span></div><div><span><span class="tab"></span><span class="tab"></span><span class="primitive">string</span><span class="space"></span><span class="name">url</span><span>;</span></span></div><div><span><span class="tab"></span><span class="tab"></span><span class="primitive">string</span><span class="space"></span><span class="name">remote_md5</span><span>;</span></span></div><div><span><span class="tab"></span><span class="tab"></span><span class="primitive">string</span><span class="space"></span><span class="name">remote_sha1</span><span>;</span></span></div><span class="tab"></span><span>}</span></span><span class="space"></span><span class="name" id="typedefAbstractHandle.Handle">Handle</span><span>;</span></span></div><br><div><span class="funcdef"><div class="comment"><div><span class="tab"></span><span>/*</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>The persist_handle writes the handle to a persistent store that can be later retrieved using the list_handles function.</span></div><div><span class="tab"></span><span class="space"></span><span>*/</span></div></div><span class="tab"></span><span class="keyword">funcdef</span><span class="space"></span><span class="name" id="funcdefAbstractHandle.persist_handle">persist_handle</span><span>(</span><span class="parameters"><span class="parameter"><span class="name"><a href="#typedefAbstractHandle.Handle">Handle</a></span><span class="space"></span><span class="name">handle</span></span></span><span>)</span><span class="space"></span><span class="keyword">returns</span><span>(</span><span class="returns"><span class="parameter"><span class="primitive">string</span><span class="space"></span><span class="name">hid</span></span></span><span>)</span><span class="space"></span><span class="keyword">authentication</span><span class="space"></span><span class="keyword">required</span><span>;</span></span></div><br><div><span class="funcdef"><div class="comment"><div><span class="tab"></span><span>/*</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>Given a list of handle ids, this function returns a list of handles.</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>This method is replaced by fetch_handles_by.</span></div><div><span class="tab"></span><span class="space"></span><span>*/</span></div></div><span class="tab"></span><span class="keyword">funcdef</span><span class="space"></span><span class="name" id="funcdefAbstractHandle.hids_to_handles">hids_to_handles</span><span>(</span><span class="parameters"><span class="parameter"><span><span class="primitive">list</span><span><</span><span class="name"><a href="#typedefAbstractHandle.HandleId">HandleId</a></span><span>></span></span><span class="space"></span><span class="name">hids</span></span></span><span>)</span><span class="space"></span><span class="keyword">returns</span><span>(</span><span class="returns"><span class="parameter"><span><span class="primitive">list</span><span><</span><span class="name"><a href="#typedefAbstractHandle.Handle">Handle</a></span><span>></span></span><span class="space"></span><span class="name">handles</span></span></span><span>)</span><span class="space"></span><span class="keyword">authentication</span><span class="space"></span><span class="keyword">required</span><span>;</span></span></div><br><div><span class="funcdef"><div class="comment"><div><span class="tab"></span><span>/*</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>Given a list of ids, this function returns a list of handles.</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>In case of Shock, the list of ids are shock node ids.</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>This method is replaced by fetch_handles_by.</span></div><div><span class="tab"></span><span class="space"></span><span>*/</span></div></div><span class="tab"></span><span class="keyword">funcdef</span><span class="space"></span><span class="name" id="funcdefAbstractHandle.ids_to_handles">ids_to_handles</span><span>(</span><span class="parameters"><span class="parameter"><span><span class="primitive">list</span><span><</span><span class="name"><a href="#typedefAbstractHandle.NodeId">NodeId</a></span><span>></span></span><span class="space"></span><span class="name">ids</span></span></span><span>)</span><span class="space"></span><span class="keyword">returns</span><span>(</span><span class="returns"><span class="parameter"><span><span class="primitive">list</span><span><</span><span class="name"><a href="#typedefAbstractHandle.Handle">Handle</a></span><span>></span></span><span class="space"></span><span class="name">handles</span></span></span><span>)</span><span class="space"></span><span class="keyword">authentication</span><span class="space"></span><span class="keyword">required</span><span>;</span></span></div><br><div><span class="typedef"><div class="comment"></div><span class="tab"></span><span class="keyword">typedef</span><span class="space"></span><span><span class="primitive">structure</span><span class="space"></span><span>{</span><div><span><span class="tab"></span><span class="tab"></span><span><span class="primitive">list</span><span><</span><span class="primitive">string</span><span>></span></span><span class="space"></span><span class="name">elements</span><span>;</span></span></div><div><span><span class="tab"></span><span class="tab"></span><span class="primitive">string</span><span class="space"></span><span class="name">field_name</span><span>;</span></span></div><span class="tab"></span><span>}</span></span><span class="space"></span><span class="name" id="typedefAbstractHandle.FetchHandlesParams">FetchHandlesParams</span><span>;</span></span></div><br><div><span class="funcdef"><div class="comment"><div><span class="tab"></span><span>/*</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>This function select records if field column entry is in elements and returns a list of handles.</span></div><div><span class="tab"></span><span class="space"></span><span>*/</span></div></div><span class="tab"></span><span class="keyword">funcdef</span><span class="space"></span><span class="name" id="funcdefAbstractHandle.fetch_handles_by">fetch_handles_by</span><span>(</span><span class="parameters"><span class="parameter"><span class="name"><a href="#typedefAbstractHandle.FetchHandlesParams">FetchHandlesParams</a></span><span class="space"></span><span class="name">params</span></span></span><span>)</span><span class="space"></span><span class="keyword">returns</span><span>(</span><span class="returns"><span class="parameter"><span><span class="primitive">list</span><span><</span><span class="name"><a href="#typedefAbstractHandle.Handle">Handle</a></span><span>></span></span><span class="space"></span><span class="name">handles</span></span></span><span>)</span><span class="space"></span><span class="keyword">authentication</span><span class="space"></span><span class="keyword">required</span><span>;</span></span></div><br><div><span class="funcdef"><div class="comment"><div><span class="tab"></span><span>/*</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>Given a list of handle ids, this function determines if the underlying data is owned by the caller.</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>If any one of the handle ids reference unreadable data this function returns false.</span></div><div><span class="tab"></span><span class="space"></span><span>*/</span></div></div><span class="tab"></span><span class="keyword">funcdef</span><span class="space"></span><span class="name" id="funcdefAbstractHandle.is_owner">is_owner</span><span>(</span><span class="parameters"><span class="parameter"><span><span class="primitive">list</span><span><</span><span class="name"><a href="#typedefAbstractHandle.HandleId">HandleId</a></span><span>></span></span><span class="space"></span><span class="name">hids</span></span></span><span>)</span><span class="space"></span><span class="keyword">returns</span><span>(</span><span class="returns"><span class="parameter"><span class="primitive">int</span></span></span><span>)</span><span class="space"></span><span class="keyword">authentication</span><span class="space"></span><span class="keyword">required</span><span>;</span></span></div><br><div><span class="funcdef"><div class="comment"><div><span class="tab"></span><span>/*</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>The delete_handles function takes a list of handles and deletes them on the handle service server.</span></div><div><span class="tab"></span><span class="space"></span><span>*/</span></div></div><span class="tab"></span><span class="keyword">funcdef</span><span class="space"></span><span class="name" id="funcdefAbstractHandle.delete_handles">delete_handles</span><span>(</span><span class="parameters"><span class="parameter"><span><span class="primitive">list</span><span><</span><span class="name"><a href="#typedefAbstractHandle.Handle">Handle</a></span><span>></span></span><span class="space"></span><span class="name">handles</span></span></span><span>)</span><span class="space"></span><span class="keyword">returns</span><span>(</span><span class="returns"><span class="parameter"><span class="primitive">int</span><span class="space"></span><span class="name">deleted_count</span></span></span><span>)</span><span class="space"></span><span class="keyword">authentication</span><span class="space"></span><span class="keyword">required</span><span>;</span></span></div><br><div><span class="funcdef"><div class="comment"><div><span class="tab"></span><span>/*</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>Given a list of handle ids, this function determines if the underlying data is readable by the caller.</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>If any one of the handle ids reference unreadable data this function returns false.</span></div><div><span class="tab"></span><span class="space"></span><span>*/</span></div></div><span class="tab"></span><span class="keyword">funcdef</span><span class="space"></span><span class="name" id="funcdefAbstractHandle.are_readable">are_readable</span><span>(</span><span class="parameters"><span class="parameter"><span><span class="primitive">list</span><span><</span><span class="name"><a href="#typedefAbstractHandle.HandleId">HandleId</a></span><span>></span></span><span class="space"></span><span class="name">hids</span></span></span><span>)</span><span class="space"></span><span class="keyword">returns</span><span>(</span><span class="returns"><span class="parameter"><span class="primitive">int</span></span></span><span>)</span><span class="space"></span><span class="keyword">authentication</span><span class="space"></span><span class="keyword">required</span><span>;</span></span></div><br><div><span class="funcdef"><div class="comment"><div><span class="tab"></span><span>/*</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>Given a handle id, this function queries the underlying data store to see if the data being referred to is readable to by the caller.</span></div><div><span class="tab"></span><span class="space"></span><span>*/</span></div></div><span class="tab"></span><span class="keyword">funcdef</span><span class="space"></span><span class="name" id="funcdefAbstractHandle.is_readable">is_readable</span><span>(</span><span class="parameters"><span class="parameter"><span class="name"><a href="#typedefAbstractHandle.HandleId">HandleId</a></span><span class="space"></span><span class="name">hid</span></span></span><span>)</span><span class="space"></span><span class="keyword">returns</span><span>(</span><span class="returns"><span class="parameter"><span class="primitive">int</span></span></span><span>)</span><span class="space"></span><span class="keyword">authentication</span><span class="space"></span><span class="keyword">required</span><span>;</span></span></div><br><div><span class="funcdef"><div class="comment"><div><span class="tab"></span><span>/*</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>The add_read_acl function will update the acl of the shock node that the handle references.</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>The function is only accessible to a specific list of users specified at startup time.</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>The underlying shock node will be made readable to the user requested.</span></div><div><span class="tab"></span><span class="space"></span><span>*/</span></div></div><span class="tab"></span><span class="keyword">funcdef</span><span class="space"></span><span class="name" id="funcdefAbstractHandle.add_read_acl">add_read_acl</span><span>(</span><span class="parameters"><span class="parameter"><span><span class="primitive">list</span><span><</span><span class="name"><a href="#typedefAbstractHandle.HandleId">HandleId</a></span><span>></span></span><span class="space"></span><span class="name">hids</span></span><span>,</span><span class="space"></span><span class="parameter"><span class="primitive">string</span><span class="space"></span><span class="name">username</span></span></span><span>)</span><span class="space"></span><span class="keyword">returns</span><span>(</span><span class="returns"><span class="parameter"><span class="primitive">int</span></span></span><span>)</span><span class="space"></span><span class="keyword">authentication</span><span class="space"></span><span class="keyword">required</span><span>;</span></span></div><br><div><span class="funcdef"><div class="comment"><div><span class="tab"></span><span>/*</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>The set_public_read function will update the acl of the shock node that the handle references to make the node globally readable.</span></div><div><span class="tab"></span><span class="space"></span><span>*</span><span class="space"></span><span>The function is only accessible to a specific list of users specified at startup time.</span></div><div><span class="tab"></span><span class="space"></span><span>*/</span></div></div><span class="tab"></span><span class="keyword">funcdef</span><span class="space"></span><span class="name" id="funcdefAbstractHandle.set_public_read">set_public_read</span><span>(</span><span class="parameters"><span class="parameter"><span><span class="primitive">list</span><span><</span><span class="name"><a href="#typedefAbstractHandle.HandleId">HandleId</a></span><span>></span></span><span class="space"></span><span class="name">hids</span></span></span><span>)</span><span class="space"></span><span class="keyword">returns</span><span>(</span><span class="returns"><span class="parameter"><span class="primitive">int</span></span></span><span>)</span><span class="space"></span><span class="keyword">authentication</span><span class="space"></span><span class="keyword">required</span><span>;</span></span></div><span>}</span><span>;</span></div><div class="index"><h2>Function Index</h2><div><span class="tab"></span><span class="name"><a href="#funcdefAbstractHandle.add_read_acl">add_read_acl</a></span></div><div><span class="tab"></span><span class="name"><a href="#funcdefAbstractHandle.are_readable">are_readable</a></span></div><div><span class="tab"></span><span class="name"><a href="#funcdefAbstractHandle.delete_handles">delete_handles</a></span></div><div><span class="tab"></span><span class="name"><a href="#funcdefAbstractHandle.fetch_handles_by">fetch_handles_by</a></span></div><div><span class="tab"></span><span class="name"><a href="#funcdefAbstractHandle.hids_to_handles">hids_to_handles</a></span></div><div><span class="tab"></span><span class="name"><a href="#funcdefAbstractHandle.ids_to_handles">ids_to_handles</a></span></div><div><span class="tab"></span><span class="name"><a href="#funcdefAbstractHandle.is_owner">is_owner</a></span></div><div><span class="tab"></span><span class="name"><a href="#funcdefAbstractHandle.is_readable">is_readable</a></span></div><div><span class="tab"></span><span class="name"><a href="#funcdefAbstractHandle.persist_handle">persist_handle</a></span></div><div><span class="tab"></span><span class="name"><a href="#funcdefAbstractHandle.set_public_read">set_public_read</a></span></div><h2>Type Index</h2><div><span class="tab"></span><span class="name"><a href="#typedefAbstractHandle.FetchHandlesParams">FetchHandlesParams</a></span></div><div><span class="tab"></span><span class="name"><a href="#typedefAbstractHandle.Handle">Handle</a></span></div><div><span class="tab"></span><span class="name"><a href="#typedefAbstractHandle.HandleId">HandleId</a></span></div><div><span class="tab"></span><span class="name"><a href="#typedefAbstractHandle.NodeId">NodeId</a></span></div></div></body></html>