rev 105 - trunk/doc

Author: mrowe
Date: 2004-04-30 01:27:34 +1200 (Fri, 30 Apr 2004)
New Revision: 105

Modified:
   trunk/doc/overview.txt
Log:
Add a beginnings of task-based documentation.

Modified: trunk/doc/overview.txt
===================================================================
--- trunk/doc/overview.txt      2004-04-29 12:55:57 UTC (rev 104)
+++ trunk/doc/overview.txt      2004-04-29 13:27:34 UTC (rev 105)
@@ -25,9 +25,9 @@
 
 .. _MSN Messenger protocol documentation: http://hypothetic.org/docs/msn/
 
----------------------
-``libmsn``
----------------------
+------------------------------
+An Introduction to ``libmsn``
+------------------------------
 
 ``libmsn`` is a single-threaded, asynchronous library that is written in  
``C++``.  All of it's code is defined within the namespace ``MSN``.  In this 
documentation, the qualifying ``MSN::`` will omitted for the sake of brevity.
 
@@ -94,7 +94,7 @@
      // Retrieve the connection associated with the
      // socket's file handle on which the event has
      // occurred.
-     c = mainconn->connectionWithSocket(mySockets[i].fd);
+     c = mainConnection->connectionWithSocket(mySockets[i].fd);
 
      // if this is a libmsn socket
      if (c != NULL)
@@ -120,7 +120,7 @@
      // Retrieve the connection associated with the
      // socket's file handle on which the event has
      // occurred.
-     c = mainconn->connectionWithSocket(mySockets[i].fd);
+     c = mainConnection->connectionWithSocket(mySockets[i].fd);
 
      // if this is a libmsn socket
      if (c != NULL)
@@ -128,8 +128,13 @@
          // Delete the connection.  This will cause the resources
          // that are being used to be freed.
          delete c;
-     }     
+     }
 
+These four steps are all that is required to use ``libmsn``.  Your program 
code can then use the ``API`` that is provided to manipulate your buddy list, 
`request switchboard sessions`_, and `send instant messages`_.
+
+.. _request switchboard sessions: `Requesting a Switchboard Session`_
+.. _send instant messages: `Sending Instant Messages`_
+
 Callbacks
 ==========
 
@@ -150,4 +155,42 @@
 Optional Callbacks
 -------------------
 
-All other callback functions may optionally be implemented.  If you have no 
use for the callback, it may be defined as an empty function.
\ No newline at end of file
+All other callback functions may optionally be implemented.  If you have no 
use for the callback, it may be defined as an empty function.
+
+
+-------------
+Common Tasks
+-------------
+
+Requesting a Switchboard Session
+=================================
+
+A switchboard connection is required for interaction with any other buddy on 
the MSN Messenger service.
+
+You can use the ``NotificationServerConnection``'s 
``requestSwitchboardConnection`` method to request a session.  You may pass an 
optional piece of data as the ``tag`` argument so that you can identify this 
switchboard request::
+
+    // Request a switchboard session, using requestContext to allow
+    // us to identify this session request
+
+    void *requestContext = <some data>;
+    mainConnection->requestSwitchboardConnection(requestContext);
+
+``MSN::ext::gotSwitchboard`` will be called when the requested switchboard 
session is established.
+
+
+Inviting Buddies Into a Switchboard Session
+============================================
+
+Once you have established a switchboard session, you need to invite your 
receiving buddy into the session.  You can do this by using the 
``SwitchboardServerConnection``'s ``inviteUser`` method.  Note that the buddy 
is not considered to have joined the session until 
``MSN::ext::buddyJoinedConversation`` has been called with the switchboard 
server and buddy as arguments.
+
+Sending Instant Messages
+=========================
+
+When your switchboard session has been established, and buddies invited, you 
can then send an instant message.  ``libmsn`` represents messages with it's 
``Message`` class, so an instance needs to be created that contains the message 
that you wish to send.  This instance will then allow you to control such 
things as the font and color that the message will appear in.  The message can 
then be transmitted into the switchboard session by using the 
``SwitchboardServerConnection``'s ``sendMessage`` method::
+
+    MSN::SwitchboardServerConnection *theSwitchboard = <a switchboard 
connection>;
+    MSN::Message msg(myMessageText);
+    msg.setFontName("Courier New");
+    msg.setFontEffects(MSN::Message::ITALIC_FONT);
+
+    theSwitchboard->sendMessage(&msg);
\ No newline at end of file



-------------------------------------------------------
This SF.Net email is sponsored by: Oracle 10g
Get certified on the hottest thing ever to hit the market... Oracle 10g. 
Take an Oracle 10g class now, and we'll give you the exam FREE. 
http://ads.osdn.com/?ad_id=3149&alloc_id=8166&op=click