################################################################################
#
# OCS Inventory NG Management Server Setup
#
# Copyleft 2008 OCS Inventory NG Team
# Web: http://www.ocsinventory-ng.org
#
# This code is open source and may be copied and modified as long as the source
# code is always made freely available.
# Please refer to the General Public Licence http://www.gnu.org/ or Licence.txt
################################################################################



soap-client is a sample that enable you to discover the ocs web service.
By default, it calls get_computer_V1 method that takes XML as argument.
You can configure this XML using script parameters.
To use other methods, (see Apache::Ocsinventory::Interface) , call it with
-f=method_name and -params='comma separated args'

# Parameters
# -s=''                         : server to query
# -u=''                         : user to authenticate
# -pw=''                        : user's password
# -params='...,...,...,...'     : Method's args                                                                                                                  
# -proto='http|https'           : Transport protocol
#
# get_computers V1 secific parameters (enable you to easily modify XML values)
# -o=''                         : offset value (to iterate if whome result is upper than OCS_OPT_WEB_SERVICE_RESULTS_LIMIT (see ocsinventory-server.conf)
# -c=''                         : checksum to compare with
# -w=''                         : same principle than checksum but for other sections (dico_soft and accountinfos for the moment)
# -t=''                         : type (META || INVENTORY)) See web service documentation

In addition to CHECKSUM (&), you can also request on :
=> userid list
=> tag list
=> database id list. 

You can use these criterias in only one request, and you can put few values for each.

For example:

<REQUEST>
  <ENGINE>FIRST</ENGINE> <= The name of the search engine (only this one is implemented for the moment)
  <ASKING_FOR>INVENTORY</ASKING_FOR> <= We want inventory date (oposite to META DATA)
  <CHECKSUM>1</CHECKSUM>         <= We want only hardware section (if it changed since our last reset_checksum) See below.
  <OFFSET>3</OFFSET>		 <= We want the third page of the result
  <WANTED>2</WANTED>		 <= We want to use the software dictionnary and the accountinfos
  <USERID>foo</USERID>		 <= We want the computers on those foo logged in
  <USERID>bar</USERID>		 <= ...where bar logged in
  <TAG>room109</TAG>		 <= We want the computer which have the "room109 tag"
  <TAG>room110</TAG>		 <= ...or the "room110" tag
  <TAG>spare</TAG>		 <= ...or th "spare" tag
  <ID>35</ID>			 <= Only the DATABASE ID 35
  <ID>36</ID>			 <= ...or 36
</REQUEST>



SOAP methods available :

Name : get_computers_V1
Args : XML string
Returns : XML
Description : Main function to deal with ocsinventory computer's data (see above)

Name : reset_checksum_V1
Args : a checksum, a list of Databases IDs
Returns : undef on system error, "0E0" if no computers matched or the number of computers on success
Description : The checksum is a bitmap used to know which inventory section has changed since last come. See Apache::Ocsinventory::Map to know the different values. For example, "hardware" section is the first bit (1). if 1 & checksum are true, you know that hardware changed since the last check.

Name : ocs_config_V1
Args : option name, value
Returns : value (if ok, ==value arg) or XML error (<RESULT><ERROR>LABEL</ERROR></RESULT>)
Description : Configure ocs with an external tool

Name : ocs_config_V2
Args : option name, integer value, string value
Returns : XML. In case of success : <RESULT><IVALUE></IVALUE><TVALUE></TVALUE></RESULT>, in case of error, the same as above.
Description : Handle the new ocs config sytem (see Apache::Ocsinventory::Server::System::Config)

Name : get_dico_soft_element_V1
Args : a word to look for
Returns : The "formatted" name (also known as category)
Description : Get the ditionnary entry of an extracted software name

Name : get_history_V1
Args : page number
Returns : XML.  <EVENT><DATE>AAAA-MM-DD HH:MM:SS</DATE><DELETED>DEVICEID</DELETED><EQUIVALENT>DEVICEID</EQUIVALENT></EVENT> ordered by date.
Description : useful to know which computers has been deleted or merges (duplicates). If a "DELETED" has no "EQUIVALENT", it is a deletion.

# Clear computer's history
Name : clear_history_V1
Args : A number of events (the former)
Returns : The number of events deleted
Description : Clear computer's history

Name : get_ipdiscover_devices_V1
Args : Date, Page, ninv flag
Returns : XML. On error : <RESULT><ERROR>LABEL</ERROR></RESULT>, on success <RESULT><IFACE><DATE>AAAA-MM-DD HH:MM:SS</DATE><IP>IPADDRESS</IP><MAC>MACADDRESS</MAC><MASK>IPMASK</MASK><NAME>hostname</NAME></IFACE>...<IFACE/>...</RESULT>
Description : Enable you to query ipdiscover results. The nInv flags ask to the method to only send the uninventories devices

Name : ipdiscover_tag_V1
Args : macaddress, description, type, user
Returns : XML
Description : Register a macaddress as you can do in GUI. The type and the user must be valid in ocs database.

Name : ipdiscover_untag_V1
Args : macaddress
Returns : XML
Description : Unregister a device

Name : ipdiscover_remove_V1
Args : macaddress
Returns : XML
Description : Delete a device from ipdiscover results

Name : ipdiscover_create_type_V1
Args : type name
Returns : XML
Description : Enable you to create a type remotely

Name : ipdiscover_delete_type_V1
Args : type name
Returns : XML
Description :  Remove a type

For further details, see http://www.ocsinventory-ng.org/index.php?mact=News,cntnt01,detail,0&cntnt01articleid=98&cntnt01returnid=80