From 77a72b94441233c912e1a4b5a4ee595a5a4d8ab7 Mon Sep 17 00:00:00 2001 From: Uwe Steinmann Date: Wed, 10 Apr 2002 13:49:54 +0000 Subject: [PATCH] - added documentation for new Hyperwave extension git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@77561 c90b9560-bf6c-de11-be94-00142212c4b1 --- functions/hwapi.xml | 1591 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1591 insertions(+) create mode 100644 functions/hwapi.xml diff --git a/functions/hwapi.xml b/functions/hwapi.xml new file mode 100644 index 0000000000..46375cefab --- /dev/null +++ b/functions/hwapi.xml @@ -0,0 +1,1591 @@ + + Hyperwave API functions + Hyperwave API + + + + + Introduction + + Hyperwave has been developed at IICM in Graz. It started with + the name Hyper-G and changed to Hyperwave when + it was commercialised (If I remember properly it was in 1996). + + + Hyperwave is not free software. The current version, 5.5, is + available at www.hyperwave.com. + A time limited version can be ordered for free (30 days). + + + Hyperwave is an information system similar to a database + (HIS, Hyperwave Information Server). Its focus + is the storage and management of documents. A document can be any + possible piece of data that may as well be stored in file. Each + document is accompanied by its object record. The object record + contains meta data for the document. The meta data is a list of + attributes which can be extended by the user. Certain attributes + are always set by the Hyperwave server, other may be modified by + the user. + + + + + Requirements + + Since 2001 there is a Hyperwave SDK available. It supports Java, + JavaScript and C++. This PHP Extension is based on the C++ interface. + In order to activate the hwapi support in PHP you will have to install + the Hyperwave SDK first. + + + + + Classes + + The API provided by the HW_API extension is fully object oriented. + It is very similar to the C++ interface of the Hyperwave SDK. + It consist of the following classes. + + + + HW_API + + + + + HW_API_Object + + + + + HW_API_Attribute + + + + + HW_API_Error + + + + + HW_API_Content + + + + + HW_API_Reason + + + + Some basic classes like HW_API_String, + HW_API_String_Array, etc., which exist in the + Hyperwave SDK have not been implemented since PHP has powerful + replacements for them. + + + Each class has certain method, whose names are identical to its + counterparts in the Hyperwave SDK. Passing arguments to this function + differs from all the other PHP Extension but is close to the C++ API of + the HW SDK. Instead of passing serval parameters they are all put into + an associated array and passed as one paramter. The names of the keys + are identical to those documented in the HW SDK. + The common parameters are listed below. If other parameters are required + they will be documented if needed. + + + + objectIdentifier The name or id of an object, + e.g. "rootcollection", "0x873A8768 0x00000002". + + + + + parentIdentifier The name or id of an object + which is considered to be a parent. + + + + + object An instance of class HW_API_Object. + + + + + parameters An instance of class HW_API_Object. + + + + + version The version of an object. + + + + + mode An integer value determine the way an + operation is executed. + + + + + attributeSelector Any array of strings, each + containing a name of an attribute. This is used if you retrieve the + object record and want to include certain attributes. + + + + + objectQuery A query to select certain object + out of a list of objects. This is used to reduce the number of objects + which was delivered by a function like + hw_api->children or hw_api->find. + + + + + + + Integration with Apache + + The integration with Apache and possible other servers is already + described in the Hyperwave Modul which has been the first extension to + connect a Hyperwave Server. + + + + + + + hwapi_hgcsp + Returns object of class hw_api + + + Description + + objecthwapi_hgcsp + stringhostname + intport + + + Opens a connection to the Hyperwave server on host + hostname. The protocol used is HGCSP. + If you do not pass a port number, 418 is used. + + + See also hwapi_hwtp. + + + + + + + hw_api->object + Retrieve attribute information + + + Description + + objecthw_api->object + arrayparameter + + + This function retrieves the attribute information of an object of any + version. It will not return the document content. The parameter array + contains the required elements 'objectIdentifier' and the optional + elements 'attributeSelector' and 'version'. + + + The returned object is an instance of class + HW_API_Object on success or + HW_API_Error if an error occured. + + + This simple example retrieves an object and checks for errors. + + Retrieve an object + +reason(0); + echo "Type: "; + switch($reason->type()) { + case 0: + echo "Error"; + break; + case 1: + echo "Warning"; + break; + case 2: + echo "Message"; + break; + } + echo "
\n"; + echo "Description: ".$reason->description("en")."
\n"; +} + +function list_attr($obj) { + echo "\n"; + $count = $obj->count(); + for($i=0; $i<$count; $i++) { + $attr = $obj->attribute($i); + printf(" \n", + $attr->key(), $attr->value()); + } + echo "
%s%s
\n"; +} + +$hwapi = hwapi_hgcsp($g_config[HOSTNAME]); +$parms = array("objectIdentifier"=>"rootcollection, "attributeSelector"=>array("Title", "Name", "DocumentType")); +$root = $hwapi->object($parms); +if(get_class($root) == "HW_API_Error") { + handle_error($root); + exit; +} +list_attr($root); +?> +]]> + + + + + See also hwapi_content. + + + + + + + hw_api->children + Returns children of an object + + + Description + + arraychildren + arrayparameter + + + Retrieves the children of a collection or the attributes of a document. + The children can be further filtered by specifying an object query. + The parameter array + contains the required elements 'objectIdentifier' and the optional + elements 'attributeSelector' and 'objectQuery'. + + + The return value is an array of objects of type + HW_API_Object or + HW_API_Error. + + + See also hwapi_parents. + + + + + + + hw_api->parents + Returns parents of an object + + + Description + + arrayparents + arrayparameter + + + Retrieves the parents of an object. The parents can be further filtered by + specifying an object query. The parameter array + contains the required elements 'objectidentifier' and the + optional elements 'attributeselector' and 'objectquery'. + + + The return value is an array of objects of type + HW_API_Object or + HW_API_Error. + + + See also hwapi_children. + + + + + + + hw_api->find + Search for objects + + + Description + + arrayfind + arrayparameter + + + This functions searches for objects either by executing a key or/and full + text query. The found objects can further be filtered by an optional + object query. They are sorted by their importance. The second search + operation is relatively slow and its result can be limited to a certain + number of hits. This allows to perform an incremental search, each + returning just a subset of all found documents, starting at a given + index. The parameter array contains the 'keyquery' or/and 'fulltextquery' + depending on who you would like to search. Optional parameters are + 'objectquery', 'scope', 'lanugages' and 'attributeselector'. In case of + an incremental search the optional parameters 'startIndex', + numberOfObjectsToGet' and 'exactMatchUnit' can be passed. + + + + + + + hw_api->identify + Log into Hyperwave Server + + + Description + + objectidentify + arrayparameter + + + Logs into the Hyperwave Server. The parameter array must contain the + elements 'username' und 'password'. + + + The return value will be an object of type + HW_API_Error if identification failed or TRUE + if it was successful. + + + + + + + hw_api->remove + Delete an object + + + Description + + objectremove + arrayparameter + + + This function removes an object from the specified parent. Collections + will be removed recursively. You can pass an optional object query to + remove only those objects which match the query. An object will be + deleted physically if it is the last instance. The parameter array + contains the required elements 'objectidentifier' and 'parentidentifier'. + If you want to remove a user or group 'parentidentifier' can be skiped. + The optional parameter 'mode' determines how the deletion is performed. + In normal mode the object will not be removed physically until all + instances are removed. In physical mode all instances of the object will + be deleted imediately. In removelinks mode all references + to and from the objects will be deleted as well. In nonrecursive the + deletion is not performed recursive. Removing a collection which is not + empty will cause an error. + + + See also hwapi_move. + + + + + + + hw_api->content + Returns content of an object + + + Description + + objectcontent + arrayparameter + + + This function returns the content of a document as an object of type + hw_api_content. The parameter array + contains the required elements 'objectidentifier' and the optional + element 'mode'. The mode can be one of the constants + HW_API_CONTENT_ALLLINKS, + HW_API_CONTENT_REACHABLELINKS or HW_API_CONTENT_PLAIN. + HW_API_CONTENT_ALLLINKS means to insert all anchors even if the + destination is not reachable. HW_API_CONTENT_REACHABLELINKS tells + hw_api_content to insert only reachable links and + HW_API_CONTENT_PLAIN will lead to document without any links. + + + + + + + hw_api->copy + Copies physically + + + Description + + objectcopy + arrayparameter + + + This function will make a physical copy including the content if it + exists and returns the new object or an error object. + The parameter array contains the + required elements 'objectIdentifier' and 'destinationParentIdentifier'. + The optional parameter is 'attributeSelector'` + + + See also hwapi_move, + hwapi_link. + + + + + + + hw_api->link + Creates a link to an object + + + Description + + objectlink + arrayparameter + + + Creates a link to an object. Accessing this link is like accessing the + object to links points to. The parameter array contains the required + elements 'objectIdentifier' and 'destinationParentIdentifier'. + 'destinationParentIdentifier' is the target collection. + + + The function returns true on success or an error object. + + + See also hwapi_copy. + + + + + + + hw_api->move + Moves object between collections + + + Description + + objectmove + arrayparameter + + + + + See also hw_objrec2array. + + + + + + + hw_api->lock + Locks an object + + + Description + + objectlock + arrayparameter + + + Locks an object for exclusive editing by the user calling this function. + The object can be only unlocked by this user or the sytem user. The + parameter array contains the required element 'objectIdentifier' and the + optional parameters 'mode' and 'objectquery'. + 'mode' determines how an object is locked. + HW_API_LOCK_NORMAL means, an object is locked until it is unlocked. + HW_API_LOCK_RECURSIVE is only valid for collection and locks all objects + within th collection und possible subcollections. + HW_API_LOCK_SESSION means, an object is locked only as long as the + session is valid. + + + See also hwapi_unlock. + + + + + + + hw_api->unlock + Unlocks a locked object + + + Description + + objectunlock + arrayparameter + + + Unlocks a locked object. Only the user who has locked the object and the + system user may unlock an object. The parameter array contains the + required element 'objectIdentifier' and the optional parameters + 'mode' and 'objectquery'. The meaning of 'mode' is the same as in + function hwapi_lock. + + + Returns true on success or an object of class HW_API_Error. + + + See also hwapi_lock. + + + + + + + hw_api->replace + Replaces an object + + + Description + + objectreplace + arrayparameter + + + Replaces the attributes and the content of an object The parameter array + contains the required elements 'objectIdentifier' and 'object' and + the optional parameters 'content', 'parameters', 'mode' and + 'attributeSelector'. 'objectIdentifier' contains the object to be + replaced. 'object' contains the new object. 'content' contains the new + content. 'parameters' contain extra information for HTML documents. + HTML_Language is the letter abbreviation of the language of the title. + HTML_Base sets the base attribute of the HTML document. 'mode' can be a + combination of the following flags: + + + HW_API_REPLACE_NORMAL + + + The object on the server is replace with the object passed. + + + + + HW_API_REPLACE_FORCE_VERSION_CONTROL + + + + + + + HW_API_REPLACE_AUTOMATIC_CHECKOUT + + + + + + + HW_API_REPLACE_AUTOMATIC_CHECKIN + + + + + + + HW_API_REPLACE_PLAIN + + + + + + + HW_API_REPLACE_REVERT_IF_NOT_CHANGED + + + + + + + HW_API_REPLACE_KEEP_TIME_MODIFIED + + + + + + + + + See also hwapi_insert. + + + + + + + hw_api->insert + Inserts a new object + + + Description + + objectinsert + arrayparameter + + + Insert a new object. The object type can be user, group, document or + anchor. Depending on the type other object attributes has to be set. + The parameter array contains the required elements 'object' and 'content' + (if the object is a document) and the optional parameters 'parameters', + 'mode' and 'attributeSelector'. The 'object' must contain all attributes + of the object. 'parameters' is an object as well holding futher + attributes like the destination (attribute key is 'Parent'). 'content' is + the content of the document. 'mode' can be a + combination of the following flags: + + + HW_API_INSERT_NORMAL + + + The object in inserted into the server. + + + + + HW_API_INSERT_FORCE-VERSION-CONTROL + + + + + + + HW_API_INSERT_AUTOMATIC-CHECKOUT + + + + + + + HW_API_INSERT_PLAIN + + + + + + + HW_API_INSERT_KEEP_TIME_MODIFIED + + + + + + + HW_API_INSERT_DELAY_INDEXING + + + + + + + + + See also hwapi_replace. + + + + + + + hw_api->insertdocument + Inserts a new object of type document + + + Description + + objectinsertdocument + arrayparameter + + + This function is a shortcut for hwapi_insert. It + inserts an object with content and sets some of the attributes required + for a document. The parameter array contains the required elements + 'object', 'parentIdentifier' and 'content' and the optional elements + 'mode', 'parameter' and 'attributeSelector'. See + hwapi_insert for the meaning of each element. + + + See also hwapi_insert + hwapi_insertanchor, + hwapi_insertcollection. + + + + + + + hw_api->insertcollection + Inserts a new object of type collection + + + Description + + objectinsertcollection + arrayparameter + + + This function is a shortcut for hwapi_insert. It + inserts an object of type collection and sets some of the attributes + required + for a collection. The parameter array contains the required elements + 'object' and 'parentIdentifier' and the optional elements + 'parameter' and 'attributeSelector'. See + hwapi_insert for the meaning of each element. + + + See also hwapi_insertdocument, + hwapi_insertanchor, + hwapi_insert. + + + + + + + hw_api->insertanchor + Inserts a new object of type anchor + + + Description + + objectinsertanchor + arrayparameter + + + This function is a shortcut for hwapi_insert. It + inserts an object of type anchor and sets some of the attributes + required + for an anchor. The parameter array contains the required elements + 'object' and 'documentIdentifier' and the optional elements + 'destinationIdentifier', 'parameter', 'hint' and 'attributeSelector'. + The 'documentIdentifier' + specifies the document where the anchor shall be inserted. The target of + the anchor is set in 'destinationIdentifier' if it already exists. If the + target does not exists the element 'hint' has to be set to the name of + object which is supposed to be inserted later. Once it is inserted the + anchor target is resolved automatically. + + + See also hwapi_insertdocument, + hwapi_insertcollection, + hwapi_insert. + + + + + + + hw_api->srcanchors + Returns a list of all source anchors + + + Description + + objectsrcanchors + arrayparameter + + + Retrieves all source anchors of an object. The parameter array contains + the required element 'objectIdentifier' and the optional elements + 'attributeSelector' and 'objectQuery'. + + + See also hwapi_dstanchors. + + + + + + + hw_api->dstanchors + Returns a list of all destination anchors + + + Description + + objectdstanchors + arrayparameter + + + Retrieves all destination anchors of an object. The parameter array + contains + the required element 'objectIdentifier' and the optional elements + 'attributeSelector' and 'objectQuery'. + + + See also hwapi_srcanchors. + + + + + + + hw_api->objectbyanchor + Returns the object an anchor belongs to + + + Description + + objectobjectbyanchor + arrayparameter + + + This function retrieves an object the specified anchor belongs to. + The parameter array contains the required element 'objectIdentifier' and + the optional element 'attributeSelector'. + + + See also hwapi_dstofsrcanchor, + hwapi_srcanchors, + hwapi_dstanchors. + + + + + + + hw_api->dstofsrcanchors + Returns destination of a source anchor + + + Description + + objectdstofsrcanchors + arrayparameter + + + Retrieves the destination object pointed by the specified source anchors. + The destination object can either be a destination anchor or a whole + document. The parameters array contains the required element + 'objectIdentifier' and the optional element 'attributeSelector'. + + + See also hwapi_srcanchors, + hwapi_dstanchors, + hwapi_objectbyanchor. + + + + + + + hw_api->srcsofdst + Returns source of a destination object + + + Description + + objectsrcsofdst + arrayparameter + + + Retrieves all the source anchors pointing to the specified destination. + The destination object can either be a destination anchor or a whole + document. The parameters array contains the required element + 'objectIdentifier' and the optional element 'attributeSelector' and + 'objectQuery'. The function returns an array of objects or an error. + + + See also hwapi_dstofsrcanchor. + + + + + + + hw_api->checkin + Checks in an object + + + Description + + objectcheckin + arrayparameter + + + This function checks in an object or a whole hiearchie of objects. + The parameters array contains the required element + 'objectIdentifier' and the optional element 'version', 'comment', 'mode' + and + 'objectQuery'. 'version' sets the version of the object. It consists of + the major and minor version separated by a period. If the version is not + set, the minor version is incremented. 'mode' can be one of the following + values: + + + HW_API_CHECKIN_NORMAL + + + Checks in and commits the object. The object must be a document. + + + + + HW_API_CHECKIN_RECURSIVE + + + If the object to check in is a collection, all children will be + checked in recursively if they are documents. Trying to check in + a collection would result in an error. + + + + + HW_API_CHECKIN_FORCE_VERSION_CONTROL + + + Checks in an object even if it is not under version control. + + + + + HW_API_CHECKIN_REVERT_IF_NOT_CHANGED + + + Check if the new version is different from the last version. Unless + this is the case the object will be checked in. + + + + + HW_API_CHECKIN_KEEP_TIME_MODIFIED + + + Keeps the time modified from the most recent object. + + + + + HW_API_CHECKIN_NO_AUTO_COMMIT + + + The object is not automatically commited on checkin. + + + + + + + See also hwapi_checkout. + + + + + + + hw_api->checkout + Checks out an object + + + Description + + objectcheckout + arrayparameter + + + This function checks out an object or a whole hiearchie of objects. + The parameters array contains the required element + 'objectIdentifier' and the optional element 'version', 'mode' + and 'objectQuery'. 'mode' can be one of the following values: + + + HW_API_CHECKIN_NORMAL + + + Checks out an object. The object must be a document. + + + + + HW_API_CHECKIN_RECURSIVE + + + If the object to check out is a collection, all children will be + checked out recursively if they are documents. Trying to check out + a collection would result in an error. + + + + + + + See also hwapi_checkin. + + + + + + + hw_api->setcommitedversion + Commits version other than last version + + + Description + + objectsetcommitedversion + arrayparameter + + + Commits a version of a docuemnt. The commited version is the one which is + visible to users with read access. By default the last version is the + commited version. + + + See also hwapi_checkin, + hwapi_checkout, + hwapi_revert. + + + + + + + hw_api->user + Returns the own user object + + + Description + + objectuser + arrayparameter + + + + + See also hwapi_userlist. + + + + + + + hw_api->userlist + Returns a list of all logged in users + + + Description + + objectuserlist + arrayparameter + + + + + See also hwapi_user. + + + + + + + hw_api->hwstat + Returns statistics about Hyperwave server + + + Description + + objecthwstat + arrayparameter + + + + + See also hwapi_dcstat, + hwapi_dbstat, + hwapi_ftstat. + + + + + + + hw_api->dcstat + Returns statistics about document cache server + + + Description + + objectdcstat + arrayparameter + + + + + See also hwapi_hwstat, + hwapi_dbstat, + hwapi_ftstat. + + + + + + + hw_api->dbstat + Returns statistics about database server + + + Description + + objectdbstat + arrayparameter + + + + + See also hwapi_dcstat, + hwapi_hwstat, + hwapi_ftstat. + + + + + + + hw_api->ftstat + Returns statistics about fulltext server + + + Description + + objectftstat + arrayparameter + + + + + See also hwapi_dcstat, + hwapi_dbstat, + hwapi_hwstat. + + + + + + + hw_api->info + Returns information about server configuration + + + Description + + objectinfo + arrayparameter + + + + + See also hwapi_dcstat, + hwapi_dbstat, + hwapi_ftstat, + hwapi_hwstat. + + + + + + + hw_api_object + Creates a new instance of class hw_api_object + + + Description + + objecthw_api_object + arrayparameter + + + + + See also hwapi_lock. + + + + + + + hw_api_object->count + Returns number of attributes + + + Description + + intcount + arrayparameter + + + + + + + + + hw_api_object->title + Returns the title attribute + + + Description + + stringtitle + arrayparameter + + + + + + + + + hw_api_object->attreditable + Checks whether an attribute is editable + + + Description + + boolattreditable + arrayparameter + + + + + + + + + hw_api_object->assign + Clones object + + + Description + + objectassign + arrayparameter + + + Clones the attributes of an object. + + + + + + + hw_api_object->insert + Inserts new attribute + + + Description + + boolinsert + objectattribute + + + Adds an attribute to the object. Returns true on success and otherwise + false. + + + See also hwapi_object_remove. + + + + + + + hw_api_object->remove + Removes attribute + + + Description + + boolremove + stringname + + + Removes the attribute with the given name. Returns true on success + and otherwise false. + + + See also hwapi_object_insert. + + + + + + + hw_api_object->value + Returns value of attribute + + + Description + + stringvalue + stringname + + + Returns the value of the attribute with the given name or false if an + error occured. + + + + + + + hw_api_attribute + Creates instance of class hw_api_attribute + + + Description + + objectattribute + stringname + stringvalue + + + Creates a new instance of hw_api_attribute with the given name and value. + + + + + + + hw_api_attribute->key + Returns key of the attribute + + + Description + + stringkey + void + + + Returns the name of the attribute. + + + See also hwapi_attribute_value. + + + + + + + hw_api_attribute->value + Returns value of the attribute + + + Description + + stringvalue + void + + + Returns the value of the attribute. + + + See also hwapi_attribute_key, + hwapi_attribute_values. + + + + + + + hw_api_attribute->values + Returns all values of the attribute + + + Description + + arrayvalues + void + + + Returns all values of the attribute as an array of strings. + + + See also hwapi_attribute_value. + + + + + + + hw_api_attribute->langdepvalue + Returns value for a given language + + + Description + + stringlangdepvalue + stringlanguage + + + Returns the value in the given language of the attribute. + + + See also hwapi_attribute_value. + + + + + + + hw_api_error->count + Returns number of reasons + + + Description + + intcount + void + + + Returns the number of error reasons. + + + See also hwapi_error_reason. + + + + + + + hw_api_error->reason + Returns reason of error + + + Description + + objectreason + void + + + Returns the first error reason. + + + See also hwapi_error_count. + + + + + + + hw_api_reason->type + Returns type of reason + + + Description + + objecttype + void + + + Returns the type of a reason. + + + + + + + hw_api_reason->description + Returns description of reason + + + Description + + stringdescription + void + + + Returns the description of a reason + + + + + + + hw_api_content + Create new instance of class hw_api_content + + + Description + + stringcontent + stringcontent + stringmimetype + + + Creates a new content object from the string + content. The mimetype is set to + mimetype. + + + + + + + hw_api_content->read + Read content + + + Description + + stringread + stringbuffer + integerlen + + + Reads len bytes from the content into the given + buffer. + + + + + + + hw_api_content->mimetype + Returns mimetype + + + Description + + stringmimetype + void + + + Returns the mimetype of the content. + + + + + + +