dsfml.network.socket source code

1 /*
2  * DSFML - The Simple and Fast Multimedia Library for D
3  *
4  * Copyright (c) 2013 - 2017 Jeremy DeHaan (dehaan.jeremiah@gmail.com)
5  *
6  * This software is provided 'as-is', without any express or implied warranty.
7  * In no event will the authors be held liable for any damages arising from the
8  * use of this software.
9  *
10  * Permission is granted to anyone to use this software for any purpose,
11  * including commercial applications, and to alter it and redistribute it
12  * freely, subject to the following restrictions:
13  *
14  * 1. The origin of this software must not be misrepresented; you must not claim
15  * that you wrote the original software. If you use this software in a product,
16  * an acknowledgment in the product documentation would be appreciated but is
17  * not required.
18  *
19  * 2. Altered source versions must be plainly marked as such, and must not be
20  * misrepresented as being the original software.
21  *
22  * 3. This notice may not be removed or altered from any source distribution
23  */
24 
25 /**
26  * This class mainly defines internal stuff to be used by derived classes.
27  *
28  * The only public features that it defines, and which is therefore common to
29  * all the socket classes, is the blocking state. All sockets can be set as
30  * blocking or non-blocking.
31  *
32  * In blocking mode, socket functions will hang until the operation completes,
33  * which means that the entire program (well, in fact the current thread if you
34  * use multiple ones) will be stuck waiting for your socket operation to
35  * complete.
36  *
37  * In non-blocking mode, all the socket functions will return immediately. If
38  * the socket is not ready to complete the requested operation, the function
39  * simply returns the proper status code (Socket.Status.NotReady).
40  *
41  * The default mode, which is blocking, is the one that is generally used, in
42  * combination with threads or selectors. The non-blocking mode is rather used
43  * in real-time applications that run an endless loop that can poll the socket
44  * often enough, and cannot afford blocking this loop.
45  *
46  * See_Also:
47  * $(TCPLISTENER_LINK), $(TCPSOCKET_LINK), $(UDPSOCKET_LINK)
48  */
49 module dsfml.network.socket;
50 
51 /// Base interface for all the socket types.
52 interface Socket
53 {
54     //TODO: Add methods to this so that they can be overridden by the socket classes?
55 
56     ///Status codes that may be returned by socket functions.
57     enum Status
58     {
59         /// The socket has sent / received the data
60         Done,
61         /// The socket is not ready to send / receive data yet
62         NotReady,
63         /// The TCP socket has been disconnected
64         Disconnected,
65         /// An unexpected error happened
66         Error
67     }
68 
69     /// Special value that tells the system to pick any available port.
70     enum AnyPort = 0;
71 
72     /**
73      * Set the blocking state of the socket.
74      *
75      * In blocking mode, calls will not return until they have completed their
76      * task. For example, a call to `receive` in blocking mode won't return
77      * until some data was actually received.
78      *
79      * In non-blocking mode, calls will
80      * always return immediately, using the return code to signal whether there
81      * was data available or not. By default, all sockets are blocking.
82      *
83      * By default, all sockets are blocking.
84      *
85      * Params:
86      * blocking = true to set the socket as blocking, false for non-blocking
87      */
88     void setBlocking(bool blocking);
89 
90     /**
91      * Tell whether the socket is in blocking or non-blocking mode.
92      *
93      * Returns: true if the socket is blocking, false otherwise.
94      */
95     bool isBlocking() const;
96 }
97