cimclient.h

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

//%2003////////////////////////////////////////////////////////////////////////
//
// 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.
//
// 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.
//
//==============================================================================
//
// Author: Mike Brasher ([e-mail])
//
// Modified By: Nitin Upasani, Hewlett-Packard Company ([e-mail])
//              Yi Zhou, Hewlett-Packard Company ([e-mail])
//              Nag Boranna, Hewlett-Packard Company ([e-mail])
//              Roger Kumpf, Hewlett-Packard Company ([e-mail])
//              Carol Ann Krug Graves, Hewlett-Packard Company
//                  ([e-mail])
//              Jair Santos, Hewlett-Packard Company ([e-mail])
//
//%/////////////////////////////////////////////////////////////////////////////

#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
    );

#ifdef PEGASUS_USE_DEPRECATED_INTERFACES
    /** connect - Creates an HTTP connection with the server
        defined by the URL in address.
        @param address - Specifies the server as a String that the client connects to.  
        @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 the 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;
            client.connect("localhost:5988");
        </PRE>
    */
    void connect(
        const String& address,
        const String& userName = String::EMPTY,
        const String& password = String::EMPTY
    );

    /** connect - Creates an HTTP connection with the server defined by the URL in address.
        @param address - Specifies the server as a String that the client connects to.  
        @param sslContext - 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.
        <PRE>
            TBD
        </PRE>
    */
    void connect(
        const String& address,
        const SSLContext& sslContext,
        const String& userName = String::EMPTY,
        const String& password = String::EMPTY
    );
#endif

    /** 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();