cimclient.h

Pegasus is an open-source implementationof the DMTF CIM and WBEM standards. It is designed to be por

//%2004////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
// Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
// Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
// IBM Corp.; EMC Corporation, The Open Group.
// Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
// IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
// 
// THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
// ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
// "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
// LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
// PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
// ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
//
//==============================================================================
//
//%/////////////////////////////////////////////////////////////////////////////

#ifndef Pegasus_Client_h
#define Pegasus_Client_h

#include <Pegasus/Common/Config.h>
#include <Pegasus/Common/String.h>
#include <Pegasus/Common/CIMName.h>
#include <Pegasus/Common/SSLContext.h>
#include <Pegasus/Common/CIMObject.h>
#include <Pegasus/Common/CIMClass.h>
#include <Pegasus/Common/CIMInstance.h>
#include <Pegasus/Common/CIMObjectPath.h>
#include <Pegasus/Common/CIMValue.h>
#include <Pegasus/Common/CIMParamValue.h>
#include <Pegasus/Common/CIMPropertyList.h>
#include <Pegasus/Common/CIMQualifierDecl.h>
#include <Pegasus/Common/Exception.h>
#include <Pegasus/Client/CIMClientException.h>
#include <Pegasus/Client/Linkage.h>
#include <Pegasus/Common/AcceptLanguages.h> //l10n


PEGASUS_NAMESPACE_BEGIN

class CIMClientInterface;


/** This class provides the interface that a client uses to communicate
with a CIM server.  This class constructs a CIM client on the local host 
(default) or the specified host.  This class invokes the CIM object 
manager for this client to perform operations such as, adding, modifying, 
or deleting a CIM class, CIM instance, and CIM qualifier type in a 
namespace.  

A client connects to a CIM Object Manager to establish an initial 
connection when it needs to perform CIM operations.  

This class defines the external client operations for Pegasus These
operations are based on the WBEM operations defined in the DMTF CIM
CIMOperations over HTTP operations Specification. They duplicate the names,
functions, and parameters of those CIMOperations. Each WBEM operation is a
method in this class.
The CIMClient Class includes all of the operations defined in version
1.1 Final of the DMTF CIM Operations over HTTP specification.
    
The CIMClient class performs the following functions:
   <ul>
   <li> connection services to local host or specified host through <tt>connect<tt>
    methods
    <li>Language choice services for the connection through a set of language
    selection functions.
    <li>Execution of CIM Operations as defined in the DMTF CIM Operations over
    HTTP specification using methods with almost exactly the same names and the
    same parameter sets as the operations defined in that document. Note that one key
    difference is that if errors occur in these operations, rather than returning an
    error code, these C++ methods all return errors that occurred on the remote server
    as well as any local errors through exceptions. 
   </ul>

<B>Exceptions and the CIMClient APIs</B> - TBD
DOCUMENTATIONSTATUS: in process.  Generally documentation in place but much reflects
    the spec, not our APIs.  Also exception processing needs work. KS 12 Nov 2003
*/
class PEGASUS_CLIENT_LINKAGE CIMClient
{
public:

    /** Constructs a CIM Client object with null values (default constructor).
    */
    CIMClient();

    /** Destructor for a CIM Client object.
    */
    ~CIMClient();

    /** gets the current timeout value in milliseconds for the CIMClient object.
	*/
    Uint32 getTimeout() const;

    /** Sets the timeout in milliseconds for the CIMClient.
        @param timeoutMilliseconds Defines the number of milliseconds the
        CIMClient will wait for a response to an outstanding request.  If a
        request times out, the connection gets reset (disconnected and
        reconnected).  Default is 20 seconds (20000 milliseconds).
    */
    void setTimeout(Uint32 timeoutMilliseconds);

    /** Creates an HTTP connection with the CIM server defined by the host and portNumber.
        @param host Specifies the server as a String that the client connects to.
        @param portNumber Uint32 defines the port number for the server and client to use.
        @param userName String that defines the name of the user that the client is connecting as.
        @param password String that contains the password of the user the client is connecting as.
        @return The return is void. Any normal return indicates a successful connection. Any exception
        indicates an error in the attempt to connect.
        @exception AlreadyConnectedException
            If a connection between the client and CIM server is already established.
        @exception InvalidLocatorException
            If the specified address is improperly formed.
        @exception CannotCreateSocketException
            If a socket cannot be created.
        @exception CannotConnectException
            If the socket connection fails.
        @exception CIMClientConnectionException
            If any other failure occurs.
        <PRE>
            CIMClient client;
            String host("localhost");
            try
            {
                client.connect(host, 5988, "guest", "guest");
            }
            catch(Exception& e)
            {
                cerr << "Pegasus Exception: " << e.getMessage() <<
                    ". Trying to connect to " << host << endl;
            }
        
        </PRE>
    */
    void connect(
        const String& host,
        const Uint32 portNumber,
        const String& userName,
        const String& password
    );

    /** Creates an HTTP connection with the server defined by the URL address.
        @param host Specifies the server that the client connects to.  The server
        is specified as a String.
        @param portNumber Uint32 defines the port number for the server and client to use.
        @param sslContext Specifies the SSL context to use for this connection.
        @param userName String that defines the name of the user that 
        the client is connecting as.
        @param password String containing the password of the user
        the client is connecting as.
        @exception AlreadyConnectedException
            If a connection between the client and CIM server is already established.
        @exception InvalidLocatorException
            If the specified address is improperly formed.
        @exception CannotCreateSocketException
            If a socket cannot be created.
        @exception CannotConnectException
            If the socket connection fails.
        @exception CIMClientConnectionException
            If any other failure occurs.
    */
    void connect(
        const String& host,
        const Uint32 portNumber,
        const SSLContext& sslContext,
        const String& userName,
        const String& password
    );

    /** Creates connection to the server for
        Local clients. The connectLocal connects to the CIM server
        running on the local system in the default location.  The
        connection is automatically authenticated for the current
        user.
        @See connect - The exceptions are defined in connect.
    */
    void connectLocal();

    /** If the connection to the server was open, the connection with the server closes;
        otherwise, it returns.  Before opening a new connection, clients should 
        use this method to close the open connection.  
    */
    void disconnect();

#ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES
// l10n start
    /** <I><B>Experimental Interface</B></I><BR>
        Sets the accept languages that will be used on the next request.
        Accept languages are the preferred languages that are to be
        returned on the response to the next request.
        @param langs - REVIEWERS: Complete this
    */	
	void setRequestAcceptLanguages(const AcceptLanguages& langs);

    /** <I><B>Experimental Interface</B></I><BR>
        Gets the accept languages that will be used on the next request.
        Accept languages are the preferred languages that are to be
        returned on the response to the next request.
    */
	AcceptLanguages getRequestAcceptLanguages() const;
	
    /** <I><B>Experimental Interface</B></I><BR>
        Sets the content languages that will be used on the next request.
        These content languages are the languages of the CIM objects that will
        sent on the next request.
        @param langs REVIEWERS: Complete this
    */  	
	void setRequestContentLanguages(const ContentLanguages& langs);

    /** <I><B>Experimental Interface</B></I><BR>
     * Gets the content languages that will be used on the next request.
     * These content languages are the languages of the CIM objects that will
     * sent on the next request.
    */    
	ContentLanguages getRequestContentLanguages() const;
	
    /** <I><B>Experimental Interface</B></I><BR>
     * Gets the content languages of the last response.
     * These content languages are the languages of the CIM objects, or 
     * CIM exceptions, that were returned on the last response..
    */    	
	ContentLanguages getResponseContentLanguages() const;
	
        /** <I><B>Experimental Interface</B></I><BR>
	 * REVIEWERS: Complete this
	 * 
	 */
	void setRequestDefaultLanguages();
// l10n end
#endif // PEGASUS_USE_EXPERIMENTAL_INTERFACES	


    /** The <TT>getClass</TT> method executes a CIM operation that returns
        a single CIM Class from the target Namespace where the ClassName input 
        parameter defines the name of the class to be retrieved.  
    
        @param nameSpace (Required) The <TT>nameSpace</TT> parameter is a CIMName 
        object that defines the target Namespace.  See definition of 
        \URL[Namespace]{DefinitionofTerms.html#NAMESPACE}.  
    
        @param className (Required)The <TT>className</TT> input parameter is a CIMName 
        object that defines the name of the Class to be retrieved.  
    
        @param localOnly (Boolean, Optional, default = true, Input)  If the <TT>localOnly</TT> input 
        parameter is true, this specifies that only CIM Elements (properties, 
        methods and qualifiers) overridden within the definition of the Class are 
        returned.  If false, all elements are returned.  This parameter therefore 
        effects a CIM Server-side mechanism to filter certain elements of the 
        returned object based on whether or not they have been propagated from the 
        parent Class (as defined by the PROPAGATED attribute).  
    
        @param includeQualifiers (Boolean, Optional, default = true, Input) If the 
        <TT>includeQualifiers</TT> input parameter is true, this specifies that 
        all Qualifiers for that Class (including Qualifiers on the Class and on 
        any returned Properties, Methods or CIMMethod Parameters) MUST be included 
        as elements in the response.  If false no QUALIFIER elements are present 
        in the returned Class object.  
    
        @param includeClassOrigin (Boolean,Optional, default = false, Input) If