clue · clue · Mar 4, 2014 · May 14, 2013 · May 14, 2013 · May 14, 2013
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1 @@
 /vendor
-/composer.lock
-/composer.phar
-/build
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,20 @@
+# CHANGELOG
+
+This file is a manually maintained list of changes for each release. Feel free
+to add your changes here when sending pull requests. Also send corrections if
+you spot any mistakes.
+
+## 0.2.0 (2013-XX-XX)
+
+* BC break: Whole new API regarding `SelectPoller` and dedicated `SocketSelectLoop`
+* BC break: Rename `Datagram\Datagram` to `Datagram\Socket`
+* BC break: Remove `bind()`, `connect()` and `setOptionBroadcast()` methods and
+add respective options to the `Datagram\Factory` class (#1). This is done in
+order to keep the API clean and to avoid confusion as to when it's safe to
+invoke those methods.
+* Feature: Implement common `Datagram\SocketInterface` from `clue/datagram`
+
+## 0.1.0 (2013-04-18)
+
+* First tagged release
+
diff --git a/Socket/React/Datagram/Buffer.php b/Socket/React/Datagram/Buffer.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace Socket\React\Datagram;
+
+use Datagram\Buffer as DatagramBuffer;
+
+class Buffer extends DatagramBuffer
+{
+    protected function handleWrite($data, $remoteAddress)
+    {
+        if ($remoteAddress === null) {
+            $this->socket->send($data, 0);
+        } else {
+            $this->socket->sendTo($data, 0, $remoteAddress);
+        }
+    }
+
+    protected function handlePause()
+    {
+        $this->loop->removeWriteStream($this->socket->getResource());
+    }
+
+    protected function handleResume()
+    {
+        $this->loop->addWriteStream($this->socket->getResource(), array($this, 'onWritable'));
+    }
+}
diff --git a/Socket/React/Datagram/Datagram.php b/Socket/React/Datagram/Datagram.php
diff --git a/Socket/React/Datagram/DatagramBuffer.php b/Socket/React/Datagram/DatagramBuffer.php
diff --git a/Socket/React/Datagram/Factory.php b/Socket/React/Datagram/Factory.php
@@ -2,15 +2,14 @@
 
 namespace Socket\React\Datagram;
 
-
 use React\EventLoop\StreamSelectLoop;
 use Socket\React\EventLoop\SelectPoller;
 use React\Promise\When;
 use React\Promise\Deferred;
 use React\EventLoop\LoopInterface;
 use Socket\Raw\Factory as RawFactory;
 use Socket\Raw\Socket as RawSocket;
-use \Exception;
+use Exception;
 
 class Factory
 {
@@ -25,28 +24,53 @@ public function __construct(LoopInterface $loop)
     }
 
     /**
-     * create datagram client socket connected to given address
+     * Create datagram client socket connect()ed to given remote address
+     *
+     * Please note that unlike streaming sockets (TCP/IP),
+     * datagram sockets usually have no concept of an
+     * "established connection", i.e. the remote side will NOT be notified
+     * of any "connection attempt" and no data has to be exchanged.
+     *
+     * Usually, there's no /need/ to connect() datagram sockets. If you
+     * want to send to a specific remote address, see the $remote parameter
+     * in send() as an alternative. Connect()ing the datagram client to
+     * the remote side once may be preferrable as it frees you from having
+     * to pass the remote address along with every send() call and only
+     * requires a single host name resolution instead of having to perform
+     * it with every send() call.
      *
      * @param string $address
+     * @param array  $context (optional) "bindto" or "broadcast" context options
      * @return PromiseInterface to return a \Socket\React\Datagram\Datagram
      * @uses RawFactory::createFromString()
+     * @uses RawSocket::setOption() to toggle broadcast option
+     * @uses RawSocket::bind() to bind to given local address
      * @uses RawSocket::setBlocking() to turn on non-blocking mode
      * @uses RawSocket::connect() to initiate connection
-     * @see \Socket\React\Datagram\Datagram::connect()
+     * @todo consider adding additional socket options
+     * @todo use async DNS resolver for "bindto" context
      */
-    public function createClient($address)
+    public function createClient($address, $context = array())
     {
         $that = $this;
         $factory = $this->rawFactory;
 
-        return $this->resolve($address)->then(function ($address) use ($factory, $that){
+        return $this->resolve($address)->then(function ($address) use ($factory, $that, $context){
             $scheme = 'udp';
             $socket = $factory->createFromString($address, $scheme);
             if ($socket->getType() !== SOCK_DGRAM) {
                 $socket->close();
                 throw new Exception('Not a datagram address scheme');
             }
 
+            if (isset($context['broadcast']) && $context['broadcast']) {
+                $socket->setOption(SOL_SOCKET, SO_BROADCAST, 1);
+            }
+
+            if (isset($context['bindto'])) {
+                $socket->bind($context['bindto']);
+            }
+
             $socket->setBlocking(false);
             $socket->connect($address);
 
@@ -55,27 +79,32 @@ public function createClient($address)
     }
 
     /**
-     * create datagram server socket waiting for incoming messages on the given address
+     * create datagram server socket waiting for incoming messages on the given local address
      *
      * @param string $address
+     * @param array  $context (optional) "broadcast" context option
      * @return PromiseInterface to return a \Socket\React\Datagram\Datagram
      * @uses RawFactory::createFromString()
      * @uses RawSocket::setBlocking() to turn on non-blocking mode
      * @uses RawSocket::bind() to initiate connection
      */
-    public function createServer($address)
+    public function createServer($address, $context = array())
     {
         $that = $this;
         $factory = $this->rawFactory;
 
-        return $this->resolve($address)->then(function ($address) use ($factory, $that){
+        return $this->resolve($address)->then(function ($address) use ($factory, $that, $context){
             $scheme = 'udp';
             $socket = $factory->createFromString($address, $scheme);
             if ($socket->getType() !== SOCK_DGRAM) {
                 $socket->close();
                 throw new Exception('Not a datagram address scheme');
             }
 
+            if (isset($context['broadcast']) && $context['broadcast']) {
+                $socket->setOption(SOL_SOCKET, SO_BROADCAST, 1);
+            }
+
             $socket->setBlocking(false);
             $socket->bind($address);
 
@@ -110,7 +139,7 @@ public function createIcmp6()
 
     public function createFromRaw(RawSocket $rawSocket)
     {
-        return new Datagram($rawSocket, $this->getSocketLoop());
+        return new Socket($this->getSocketLoop(), $rawSocket);
     }
 
     /**