cimclient.h

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

//%2006////////////////////////////////////////////////////////////////////////
//
// 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.
// Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
// EMC Corporation; VERITAS Software Corporation; The Open Group.
// Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
// EMC Corporation; Symantec 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/AcceptLanguageList.h>
#include <Pegasus/Common/ContentLanguageList.h>
#include <Pegasus/Client/ClientOpPerformanceDataHandler.h>


PEGASUS_NAMESPACE_BEGIN

class CIMClientInterface;

/**
    The CIMClient class provides an interface for a client application
    to communicate with a CIM Server.  The client application specifies
    the target CIM Server by providing connection parameters and
    authentication credentials (as necessary).

    The CIMClient class models the functionality defined in the DMTF's
    Specification for CIM Operations over HTTP version 1.1, using similar
    operations and parameters.
*/
class PEGASUS_CLIENT_LINKAGE CIMClient
{
public:

    /**
        Constructs a CIMClient object.
    */
    CIMClient();

    /**
        Destructs a CIMClient object.
    */
    ~CIMClient();

    /**
        Gets the currently configured timeout value for the CIMClient object.
        @return An integer indicating the currently configured timeout
        value (in milliseconds).
    */
    Uint32 getTimeout() const;

    /**
        Sets the timeout value for CIMClient operations.  If an operation
        response is not received within this timeout value, a
        ConnectionTimeoutException is thrown and the connection is reset.
        The default timeout value is 20 seconds (20000 milliseconds).
        @param timeoutMilliseconds An integer specifying the timeout value
        (in milliseconds).
    */
    void setTimeout(Uint32 timeoutMilliseconds);

    /** Connects to the CIM Server at the specified host name and port number.
        Example usage:
        <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>
        @param host A String host name to connect to.
        @param portNumber A Uint32 port number to connect to.
        @param userName A String specifying the user name for the connection.
        @param password A String containing the password of the specified user.
        @exception AlreadyConnectedException
            If the CIMClient is already connected to a CIM Server.
        @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 String& userName,
        const String& password
    );

    /** Connects to the CIM Server at the specified host name, port number
        and SSL context.
        @param host A String host name to connect to.
        @param portNumber A Uint32 port number to connect to.
        @param sslContext The SSL context to use for this connection.
        @param userName A String specifying the user name for the connection.
        @param password A String containing the password of the specified user.
        @exception AlreadyConnectedException
            If the CIMClient is already connected to a CIM Server.
        @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
    );

    /** Connects to the local CIM Server as the current user.  Authentication
        is performed automatically, so no credentials are required for this
        connection.
        @exception AlreadyConnectedException
            If the CIMClient is already connected to a CIM Server.
        @exception CannotCreateSocketException
            If a socket cannot be created.
        @exception CannotConnectException
            If the socket connection fails.
        @exception CIMClientConnectionException
            If any other failure occurs.
    */
    void connectLocal();

    /**
        Disconnects from the CIM Server.  If no connection is established,
        this method has no effect.  A CIMClient with an existing connection
        must be disconnected before establishing a new connection.
    */
    void disconnect();

#ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES
    /** <I><B>Experimental Interface</B></I><BR>
        Configures the accept languages to be specified on subsequent
        requests from this client.  Accept languages are the preferred
        languages for response data.
        @param langs An AcceptLanguageList object specifying the languages
        preferred by this client.
    */
    void setRequestAcceptLanguages(const AcceptLanguageList& langs);

    /** <I><B>Experimental Interface</B></I><BR>
        Gets the accept languages currently configured for this client.
        Accept languages are the preferred languages for response data.
        @return An AcceptLanguageList object specifying the preferred languages
        configured for this client.
    */
    AcceptLanguageList getRequestAcceptLanguages() const;

    /** <I><B>Experimental Interface</B></I><BR>
        Configures the content languages to be specified on subsequent
        requests from this client.  The content languages indicate the
        languages associated with request data sent from this client.
        @param langs A ContentLanguageList object specifying the languages
        associated with this client's request data.
    */
    void setRequestContentLanguages(const ContentLanguageList& langs);

    /** <I><B>Experimental Interface</B></I><BR>
        Gets the content languages currently configured for this client.
        The content languages indicate the languages associated with request
        data sent from this client.
        @return A ContentLanguageList object specifying the languages used in
        request data from this client.
    */
    ContentLanguageList getRequestContentLanguages() const;

    /** <I><B>Experimental Interface</B></I><BR>
        Gets the content languages of the last response received by this
        client.  The content languages indicate the languages associated
        with the data included in the response.
        @return A ContentLanguageList object specifying the languages used in
        the last response received by this client.
    */
    ContentLanguageList getResponseContentLanguages() const;

    /** <I><B>Experimental Interface</B></I><BR>
    */
    void setRequestDefaultLanguages();
#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 
        the <TT>includeClassOrigin</TT> input parameter is true, this specifies 
        that the CLASSORIGIN attribute MUST be present on all appropriate elements 
        in the returned Class.  If false, no CLASSORIGIN attributes are present in 
        the returned Class.  
    
        @param propertyList (optional, Input) If the <TT>propertyList</TT> 
        CIMPropertyList input parameter is not NULL, the members of the array