grim/purple-objects-docbook

added a bunch of information on connections

2013-06-01, Gary Kramlich
7b7ee86533d0
Parents c1dc7c6285c8
Children cd5a1edb9dd5
added a bunch of information on connections
4 files changed, 96 insertions(+), 4 deletions(-)
  • +9 -0
    graphs/connection-state.enum
  • +39 -0
    graphs/connection.class
  • +8 -3
    graphs/connections.hierarchy
  • +40 -1
    xml/connections.xml
    • --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/graphs/connection-state.enum Sat Jun 01 03:21:59 2013 -0500
    @@ -0,0 +1,9 @@
    +<?xml version="1.0" encoding="UTF-8"?>
    +<enumeration name="PurpleConnectionState">
    + <item name="PURPLE_CONNECTION_STATE_UNKNOWN" value="-1"/>
    + <item name="PURPLE_CONNECTION_STATE_DISCONNECTED" value="0"/>
    + <item name="PURPLE_CONNECTION_STATE_DISCONNECTING" value="1"/>
    + <item name="PURPLE_CONNECTION_STATE_CONNECTING" value="2"/>
    + <item name="PURPLE_CONNECTION_STATE_CONNECTED" value="3"/>
    +</enumeration>
    +
    --- /dev/null Thu Jan 01 00:00:00 1970 +0000
    +++ b/graphs/connection.class Sat Jun 01 03:21:59 2013 -0500
    @@ -0,0 +1,39 @@
    +<?xml version="1.0" encoding="UTF-8"?>
    +<class name="PurpleConnection" type="abstract">
    + <properties>
    + <property name="state" type="PurpleConnectionState" scope="private"/>
    + <property name="connection" type="PurpleConnection *" scope="private"/>
    + </properties>
    + <methods>
    + <method name="purple_connection_new" type="PurpleConnection *" scope="public">
    + <argument name="connection" type="PurpleConnection *"/>
    + </method>
    + <method name="purple_connection_get_state" type="PurpleConnectionState" scope="public">
    + <argument name="connection" type="const PurpleConnection *"/>
    + </method>
    + <method name="purple_connection_connect" type="gboolean" scope="public">
    + <argument name="connection" type="const PurpleConnection *"/>
    + </method>
    + <method name="purple_connection_disconnect" type="gboolean" scope="public">
    + <argument name="connection" type="const PurpleConnection *"/>
    + </method>
    + </methods>
    + <signals>
    + <signal name="PurpleConnection::connecting-progress" type="void" scope="public">
    + <argument name="connection" type="const PurpleConnection *"/>
    + <argument name="text" type="const gchar *"/>
    + <argument name="step" type="gint"/>
    + <argument name="step_count" type="gint"/>
    + </signal>
    + <signal name="PurpleConnection::connected" type="void" scope="public">
    + <argument name="connection" type="const PurpleConnection *"/>
    + </signal>
    + <signal name="PurpleConnection::disconnected" type="void" scope="public">
    + <argument name="connection" type="const PurpleConnection *"/>
    + </signal>
    + </signals>
    +</class>
    +
    +<!--
    + vi: syntax=xml
    +-->
    --- a/graphs/connections.hierarchy Sat Jun 01 03:21:43 2013 -0500
    +++ b/graphs/connections.hierarchy Sat Jun 01 03:21:59 2013 -0500
    @@ -2,16 +2,21 @@
    <hierarchy>
    <objects>
    <object name="GObject" type="abstract"/>
    - <object name="PurpleObject" type="abstract"/>
    <object name="PurpleConnection" type="abstract"/>
    <object name="PurpleXMPPConnection" type="concrete"/>
    +
    + <object name="PurpleSSLConnection" type="concrete"/>
    + <object name="PurpleSOCKS5Proxy" type="concrete"/>
    </objects>
    <relations>
    - <relation start="PurpleObject" end="GObject" type="is-a"/>
    - <relation start="PurpleConnection" end="PurpleObject" type="is-a"/>
    + <relation start="PurpleConnection" end="GObject" type="is-a"/>
    <relation start="PurpleXMPPConnection" end="PurpleConnection" type="is-a"/>
    + <relation start="PurpleSSLConnection" end="PurpleConnection" type="is-a"/>
    + <relation start="PurpleSSLConnection" end="PurpleXMPPConnection" type="has-a"/>
    + <relation start="PurpleSOCKS5Proxy" end="PurpleConnection" type="is-a"/>
    + <relation start="PurpleSOCKS5Proxy" end="PurpleSSLConnection" type="has-a"/>
    </relations>
    </hierarchy>
    <!--
    --- a/xml/connections.xml Sat Jun 01 03:21:43 2013 -0500
    +++ b/xml/connections.xml Sat Jun 01 03:21:59 2013 -0500
    @@ -4,10 +4,49 @@
    <chapter id="connections">
    <title>Connections</title>
    + <sect1>
    + <para>
    + Connections are a very important object in purple but up until now
    + they've been rather cubersome to use/implement since the protocol
    + plugin needs to check if we're running over SSL or via a proxy and
    + so on.
    + </para>
    + <para>
    + My proposed solution uses the
    + <ulink url="http://en.wikipedia.org/wiki/Decorator_pattern">
    + decorator pattern</ulink> to make it easier for not only the
    + protocol author, but the core as well. By decorating connections,
    + the protocol only needs to implement it's specifics.
    + </para>
    + <para>
    + If the account this connection is being created for is supposed to
    + be run over an SSL connection on port 443, the core will know this
    + from the account and then create a PurpleSSLConnection passing it
    + the options from the account and the protocol's connection.
    + </para>
    + <para>
    + The core will then dereference the protocol's connection, and call
    + connect on the SSL connection, which after setting up SSL, will
    + call the protocol connection's connect method.
    + </para>
    + </sect1>
    +
    <figure id="connections-hierarchy">
    <title>Connection Object Hierarchy</title>
    -
    +
    <graphic fileref="graphs/connections.png"/>
    </figure>
    +
    + <figure id="connection-state-enum">
    + <title>ConnectionState Enumeration</title>
    +
    + <graphic fileref="graphs/connection-state.png"/>
    + </figure>
    +
    + <figure id="connection-class">
    + <title>PurpleConnection Class</title>
    +
    + <graphic fileref="graphs/connection.png"/>
    + </figure>
    </chapter>