Source: dcop-doc.h


Annotated List
Files
Globals
Hierarchy
Index
/*
	A dummy source file for documenting the library.
	Michael Koch <koch@kde.org>
	$Id: dcop-doc.h,v 1.1 2000/01/14 10:45:05 mkoch Exp $
	Distributed under the LGPL.
*/

/**
* @libdoc The DCOP Desktop COmmunication Protocol library
*
* DCOP is a simple IPC/RPC mechanism built to operate over sockets.
* Either unix domain sockets or tcp/ip sockets are supported. DCOP is
* built on top of the Inter Client Exchange (ICE) protocol, which comes
* standard as a part of X11R6 and later. It also depends on Qt, but
* beyond that it does not require any other libraries. Because of this,
* it is extremely lightweight, enabling it to be linked into all KDE
* applications with low overhead.
* 
* Model:
* 
* The model is simple.  Each application using DCOP is a client.  They
* communicate to each other through a DCOP server, which functions like
* a traffic director, dispatching messages/calls to the proper
* destinations.  All clients are peers of each other.
* 
* Two types of actions are possible with DCOP: "send and forget"
* messages, which do not block, and "calls," which block waiting for
* some data to be returned.
* 
* Any data that will be sent is serialized (marshalled, for you CORBA
* types) using the built-in QDataStream operators available in all of the
* Qt classes.  This is fast and easy.  Currently, there is no
* type checking or parameter checking available for RPC, but this may be
* provided at some time in the future in the form of a simple IDL-like
* compiler (NOTE: 5 days later the IDL compiler is already started; 
* look in dcopidl/).  Until that is available, you will have to code
* some things by hand that normally the compiler or CORBA take care of
* automatically, but it is not a lot of work.
* 
* Establishing the Connection:
* 
* KApplication has gained a method called "KApplication::dcopClient()"
* which returns a pointer to a DCOPClient instance.  The first time this
* method is called, the client class will be created.  DCOPClients have
* unique identifiers attached to them which are based on what
* KApplication::name() returns.  In fact, if there is only a single
* instance of the program running, the appId will be equal to
* KApplication::name().
* 
* To actually enable DCOP communication to begin, you must use
* DCOPClient::attach().  This will attempt to attach to the DCOP server.
* If no server is found or there is any other type of error, attach()
* will return false.  Applications which are DCOP-enabled should
* probably do something like this at startup time:
*
* <pre> 
* client = kApp->dcopClient();
* if (!client->attach()) {
*   QMessageBox::error(this, i18n("Error connecting to DCOP server"),
*                      i18n("There was an error connecting to the Desktop\n"
*                           "communications server.  Please make sure that\n"
*                           "the 'dcopserver' process has been started, and\n"
*                           "then try again.\n"));
*   exit(1);
* }
* </pre>
* 
* After connecting with the server via @ref DCOPClient::attach, you need to
* register this appId with the server so it knows about you.  Otherwise,
* you are communicating anonymously.  Use the
* DCOPClient::registerAs(const QCString &name) to do so.  In the simple
* case:
* 
* <pre>
* // returns the appId that is actually registered, which _may_ be
* // different from what you passed
* 
* appId = client->registerAs(kApp->name());
* </pre>
* 
* If you never retrieve the DCOPClient pointer from KApplication, the
* object will not be created and thus there will be no memory overhead.
* 
* You may also detach from the server by calling DCOPClient::detach().
* If you wish to attach again you will need to re-register as well.  If
* you only wish to change the ID under which you are registered, simply
* call DCOPClient::registerAs() with the new name.
* 
* Sending Data to a Remote Application:
* 
* To actually communicate, you have one of two choices.  You may either
* call the "send" or the "call" method.  Both methods require three
* identification parameters: an application identifier, a remote object,
* a remote function. Sending is asynchronous (i.e. it returns immediately)
* and may or may not result in your own application being sent a message at
* some point in the future. Then "send" requires one and "call" requires 
* two data parameters.
* 
* The remote object must be specified as an object hierarchy.  That is,
* if the toplevel object is called "fooObject" and has the child
* "barObject", you would reference this object as "fooObject/barObject".
* Functions must be described by a full function signature.  If the
* remote function is called "doIt", and it takes an int, it would be
* described as "doIt(int)".  Please note that the return type is not
* specified here, as it is not part of the function signature (or at
* least the C++ understanding of a function signature).  You will get
* the return type of a function back as an extra parameter to
* DCOPClient::call().  See the section on call() for more details.
* 
* In order to actually get the data to the remote client, it must be
* "serialized" via a QDataStream 
*/

Generated by: root@tantive.terraplex.com on Sun Feb 27 17:39:16 2000, using kdoc 2.0a33.