[Libmsn-commits] rev 105 - trunk/doc

[<mr...@bl...>]

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