Changes

Jump to navigation Jump to search

Development Team/Almanac/Sugar.presence (view source)

Revision as of 21:32, 23 February 2010

8,256 bytes added ,  21:32, 23 February 2010
m
moved Walter is a wanker 12/Almanac/Sugar.presence to Development Team/Almanac/Sugar.presence over redirect: revert
Line 1: Line 1: −
{{Sugar Almanac}}
+
{{Almanac}}
 
=== How do I setup a D-Bus Tube? ===
 
=== How do I setup a D-Bus Tube? ===
   −
Let's first look at what conceptually happens to make activity sharing work. The diagram below shows two instances of the same activity: the "Sharing Activity" and the "Joining Activity". The sharing activity is the activity that is initially run and shared with other buddies. The "Joining Activity" refers to other instances of the activity that are created once buddies decide to join an activity that has been shared. You can allow an activity to be shared (making it a sharing activity) by  [[Sugar.presence.presenceservice#How do I share an activity with other buddies in my neighborhood? | including the standard Sugar Activity Toolbar]].
+
Let's first look at what conceptually happens to make activity sharing work. The diagram below shows two instances of the same activity: the "Sharing Activity" and the "Joining Activity". The sharing activity is the activity that is initially run and shared with other buddies. The "Joining Activity" refers to other instances of the activity that are created once buddies decide to join an activity that has been shared. You can allow an activity to be shared (making it a sharing activity) by  [[Development Team/Almanac/Sugar.presence.presenceservice#How do I share an activity with other buddies in my neighborhood? | including the standard Sugar Activity Toolbar]].
    
[[Image:tube-setup.jpg | How Tubes are Setup]]
 
[[Image:tube-setup.jpg | How Tubes are Setup]]
Line 110: Line 110:  
     def _new_tube_cb(self, id, initiator, type, service, params, state):
 
     def _new_tube_cb(self, id, initiator, type, service, params, state):
 
          
 
          
−
         if (type == telepathy.TUBE_TYPE_DBUS and service == SERVICE):
+
         if type == telepathy.TUBE_TYPE_DBUS and service == SERVICE:
 
             if state == telepathy.TUBE_STATE_LOCAL_PENDING:
 
             if state == telepathy.TUBE_STATE_LOCAL_PENDING:
 
                 #Accept the new tube that has been created  
 
                 #Accept the new tube that has been created  
Line 262: Line 262:  
[[Image:stream-tube-in-annotate-activity.jpg | How annotate's stream tube will be used]]
 
[[Image:stream-tube-in-annotate-activity.jpg | How annotate's stream tube will be used]]
   −
Notice that the stream tube exists as a complement to the [http://en.wikipedia.org/wiki/Internet_socket socket architecture] used by Unix systems to facilitate internet communication.
+
Notice that the stream tube exists on top of the [http://en.wikipedia.org/wiki/Internet_socket socket architecture] used by Unix systems to facilitate internet communication.
    
==== Step 2: Define or identify the classes you will use to serve data and receive data through your stream tube. ====
 
==== Step 2: Define or identify the classes you will use to serve data and receive data through your stream tube. ====
Line 305: Line 305:     
==== Step 3: Coordinate sharing and joining in your activity using stream tubes and the client/server classes defined above. ====
 
==== Step 3: Coordinate sharing and joining in your activity using stream tubes and the client/server classes defined above. ====
 +
 +
On the sharing instance, the following must happen:
 +
* Once the activity has been shared by the user, the sharing instance should detect the "shared" signal and setup for sharing.
 +
* To setup for sharing, the sharing instance needs to instantiate a new server (in Annotate, this is an AnnotateHTTPServer) that will deliver content to any client activities.
 +
* The newly instantiated server should listen on a given port and that port should be connected to a new stream tube. The stream tube can be created by calling the iface.OfferStreamTube() method.
 +
 +
 +
For the joining activity, it must coordinate several steps once the "joined" signal has been detected:
 +
* The joining activity needs to wait for a valid stream tube that is provided under the service ANNOTATE_STREAM_SERVICE.
 +
* When such a tube is available, the joining activity should specify the path where the downloaded data will be saved.
 +
* Create a listening client on the address and port associated with the stream tube that has been found. In our case, we create a sugar.network.GlibURLDownloader instance that will manage downloading from the stream tube.
 +
 
<pre>
 
<pre>
 
ANNOTATE_STREAM_SERVICE = 'annotate-activity-http'
 
ANNOTATE_STREAM_SERVICE = 'annotate-activity-http'
Line 314: Line 326:     
         ...
 
         ...
−
      
         #Joining activity needs to know which stream tubes are available for downloading  
 
         #Joining activity needs to know which stream tubes are available for downloading  
Line 367: Line 378:        +
    ################### COORDINATE TUBE CREATION AND DOWNLOAD IN JOINING ACTIVITY  ##################
 +
 +
    #### Method _joined_cb, which is called when this activity joins another
 +
    # instance
 +
    def _joined_cb(self, also_self):
 +
        self.watch_for_tubes()
 +
        self._want_document = True;
 +
        gobject.idle_add(self._get_document)
 +
 +
    #### Method watch_for_tubes, which sets up a callback to _new_tube_cb once
 +
    # a stream tube is made available.
 +
    def watch_for_tubes(self):
 +
        tubes_chan = self._shared_activity.telepathy_tubes_chan
 +
 +
        tubes_chan[telepathy.CHANNEL_TYPE_TUBES].connect_to_signal('NewTube',
 +
            self._new_tube_cb)
 +
        tubes_chan[telepathy.CHANNEL_TYPE_TUBES].ListTubes(
 +
            reply_handler=self._list_tubes_reply_cb,
 +
            error_handler=self._list_tubes_error_cb)
 +
 +
    def _list_tubes_reply_cb(self, tubes):
 +
        for tube_info in tubes:
 +
            self._new_tube_cb(*tube_info)
 +
 +
    def _list_tubes_error_cb(self, e):
 +
 +
    #### Method _new_tube_cb, which is called once a stream tube is available
 +
    # to download from
 +
    def _new_tube_cb(self, tube_id, initiator, tube_type, service, params,
 +
                    state):
 +
        # If the available tube is the stream tube we set up in sharing activity, then
 +
        # let's download from it.
 +
        if service == ANNOTATE_STREAM_SERVICE:           
 +
            # Add the newly found stream tube to the available tubes we can download from
 +
            self.unused_download_tubes.add(tube_id)
 +
           
 +
            # if no download is in progress, let's fetch the document
 +
            if self._want_document:
 +
                gobject.idle_add(self._get_document)
 +
 +
 +
    #### Method _get_document, which sets this activity instance up to start downloading
 +
    # the document from the sharing activity. It is called once a stream tube has been
 +
    # obtained and saved in self.unused_download_tubes.
 +
    def _get_document(self):
 +
        if not self._want_document:
 +
            return False
 +
 +
        # Assign a file path to download to -- where downloaded doc will be saved.
 +
        path = os.path.join(self.get_activity_root(), 'instance',
 +
                                '%i' % time.time())
 +
 +
        # Pick an available tube we can try to download the document from
 +
        try:
 +
            tube_id = self.unused_download_tubes.pop()
 +
        except (ValueError, KeyError), e:
 +
            return False
 +
 +
        # Avoid trying to download the document multiple times at once
 +
        self._want_document = False
 +
        gobject.idle_add(self._download_document, tube_id, path)
 +
        return False
 +
 +
 +
    #### Method _download_result_cb, which is called once downloading is complete.
 +
    def _download_result_cb(self, getter, tempfile, suggested_name, tube_id):
 +
        del self.unused_download_tubes
 +
        self.save()
 +
 +
    #### Method _download_progress_cb, which is called as the file is being downloaded.
 +
    def _download_progress_cb(self, getter, bytes_downloaded, tube_id):
 +
        # FIXME: signal the expected size somehow, so we can draw a progress
 +
        # bar
 +
        return True;
 +
 +
    #### Method _download_error_cb, which is called if there was an error downloading.
 +
    def _download_error_cb(self, getter, err, tube_id):
 +
        _logger.debug("Error getting document from tube %u: %s",
 +
                      tube_id, err)
 +
        self._want_document = True
 +
        gobject.idle_add(self._get_document)
 +
 +
   
 +
    def _download_document(self, tube_id, path):
 +
        # FIXME: should ideally have the CM listen on a Unix socket
 +
        # instead of IPv4 (might be more compatible with Rainbow)
 +
        chan = self._shared_activity.telepathy_tubes_chan
 +
        iface = chan[telepathy.CHANNEL_TYPE_TUBES]
 +
        addr = iface.AcceptStreamTube(tube_id,
 +
                telepathy.SOCKET_ADDRESS_TYPE_IPV4,
 +
                telepathy.SOCKET_ACCESS_CONTROL_LOCALHOST, 0,
 +
                utf8_strings=True)
 +
        _logger.debug('Accepted stream tube: listening address is %r', addr)
 +
        # SOCKET_ADDRESS_TYPE_IPV4 is defined to have addresses of type '(sq)'
 +
        assert isinstance(addr, dbus.Struct)
 +
        assert len(addr) == 2
 +
        assert isinstance(addr[0], str)
 +
        assert isinstance(addr[1], (int, long))
 +
        assert 0 < addr[1] < 65536
 +
        port = int(addr[1])
    +
        getter = network.GlibURLDownloader("http://%s:%d/document"
 +
                                          % (addr[0], port))
 +
        getter.connect("finished", self._download_result_cb, tube_id)
 +
        getter.connect("progress", self._download_progress_cb, tube_id)
 +
        getter.connect("error", self._download_error_cb, tube_id)
 +
        getter.start(path)
 +
        return False
    
</pre>
 
</pre>
Line 377: Line 495:     
=== Where do I get more information regarding sugar activity sharing and the technologies that support it? ===
 
=== Where do I get more information regarding sugar activity sharing and the technologies that support it? ===
−
* A [[Shared_Sugar_Activities | brief tutorial]] on activity sharing for the OLPC laptop.
+
* A [[Development Team/Almanac/Shared_Sugar_Activities | brief tutorial]] on activity sharing for the OLPC laptop.
 +
 
 +
=== I can't get tubes to work.  Are there unresolved issues? ===
 +
 
 +
==== Which threading patterns are most appropriate for use on the sugar platform? ====
 +
 
 +
<p>
 +
There are issues regarding the best way to create activities that support media sharing. In particular, the structure of DBus tubes makes it easy to customize the communication process between activity instances running on multiple XOs. However, stream tubes seem to be tied closely to a client server architecture - the servers and handlers provided in sugar.network package are some form of client/server arrangement.
 +
</p>
 +
 
 +
<p>
 +
Setting up more advanced stream tubes functionality that would allow sharing of non-text data (eg. binary files, images, etc.) in a continuous manner in the way dbus tubes enable text communication is complicated.  To allow activities to communicate constantly over a stream tube, one needs to set up both a client and server side on each activity and coordinate communication between them. Furthermore, most activities would require threading as well, which means resolving best practices for threading. Ultimately, it seems that the existing servers/handlers to support stream tubes may not be adequate to support easy and relatively painless sharing of data between activities on a continuous basis. The code that is on the Almanac right now guides a user through the basic process of setting up a stream tube and allowing communication one time between the server and client. This is useful for sharing/joining activities that require sending binary files (which is why Record and Read use this). However, it does not extend easily to peer to peer communication.
 +
</p>
 +
 
 +
<p>
 +
One solution to sending non-text data between activities is to just use the DBus tube and take advantage of its flexibility. It's not clear how well these tubes will support binary data, however and whether they work well with larger media files. It would be helpful to get insight from sugar developers regarding how such communication should work and what facilities sugar needs to add to support this (perhaps more functionality for stream tubes in sugar.network). Given that peer to peer networking through mesh is probably one of the standout features of XO laptops, I think having better functionality (and better documentation) for developers to build rich communicative applications is a high priority.
 +
</p>
Retrieved from "https://wiki.sugarlabs.org/go/Special:MobileDiff/18548...46679"

Navigation menu