| 1 |
\hypertarget{group__stream}{ |
| 2 |
\section{Socket streams} |
| 3 |
\label{group__stream}\index{Socket streams@{Socket streams}} |
| 4 |
} |
| 5 |
|
| 6 |
|
| 7 |
\subsection{Detailed Description} |
| 8 |
This API provides a functional interface to asynchronously processed socket streams. For simplicity, unlike other implementations, one stream instance can be readable and writable at the same time. Once configured, a stream must be scheduled with a task. The library will then notify the application using a notification callback, which will be called by one of the task's thread. |
| 9 |
|
| 10 |
\subsection*{Modules} |
| 11 |
\begin{CompactItemize} |
| 12 |
\item |
| 13 |
\hyperlink{group__stream__common}{Stream common} |
| 14 |
\begin{CompactList}\small\item\em Creation methods and other common methods for socket streams. \item\end{CompactList} |
| 15 |
|
| 16 |
\item |
| 17 |
\hyperlink{group__stream__low}{Non-buffered operations} |
| 18 |
\begin{CompactList}\small\item\em Low level read/write primitives. \item\end{CompactList} |
| 19 |
|
| 20 |
\item |
| 21 |
\hyperlink{group__stream__line}{Line-mode operations} |
| 22 |
\begin{CompactList}\small\item\em Line-mode based stream methods. \item\end{CompactList} |
| 23 |
|
| 24 |
\item |
| 25 |
\hyperlink{group__stream__buf}{Write-buffered operations} |
| 26 |
\begin{CompactList}\small\item\em Write-buffered stream methods. \item\end{CompactList} |
| 27 |
|
| 28 |
\item |
| 29 |
\hyperlink{group__stream__sched}{Scheduling} |
| 30 |
\begin{CompactList}\small\item\em Scheduling task for streams. \item\end{CompactList} |
| 31 |
|
| 32 |
\end{CompactItemize} |
| 33 |
\subsection*{Typedefs} |
| 34 |
\begin{CompactItemize} |
| 35 |
\item |
| 36 |
\hypertarget{group__stream_ga0}{ |
| 37 |
typedef \_\-\_\-peak\_\-stream $\ast$ \hyperlink{group__stream_ga0}{peak\_\-stream}} |
| 38 |
\label{group__stream_ga0} |
| 39 |
|
| 40 |
\begin{CompactList}\small\item\em Opaque stream pointer type. \item\end{CompactList}\item |
| 41 |
typedef void($\ast$ \hyperlink{group__stream_ga1}{peak\_\-stream\_\-event\_\-callback} )(\hyperlink{group__stream_ga0}{peak\_\-stream} s, int type, void $\ast$context) |
| 42 |
\begin{CompactList}\small\item\em Stream client event callback. \item\end{CompactList}\end{CompactItemize} |
| 43 |
\subsection*{Enumerations} |
| 44 |
\begin{CompactItemize} |
| 45 |
\item |
| 46 |
enum \{ \par |
| 47 |
\hyperlink{group__stream_gga2a5}{PEAK\_\-STREAM\_\-OPT\_\-DEFAULT} = 0, |
| 48 |
\par |
| 49 |
\hyperlink{group__stream_gga2a6}{PEAK\_\-STREAM\_\-OPT\_\-DGRAM} = 1 $<$$<$ 0, |
| 50 |
\par |
| 51 |
\hyperlink{group__stream_gga2a7}{PEAK\_\-STREAM\_\-OPT\_\-LISTEN} = 1 $<$$<$ 1, |
| 52 |
\par |
| 53 |
\hyperlink{group__stream_gga2a8}{PEAK\_\-STREAM\_\-OPT\_\-LINEMODE} = 1 $<$$<$ 2, |
| 54 |
\par |
| 55 |
\hyperlink{group__stream_gga2a9}{PEAK\_\-STREAM\_\-OPT\_\-AUTOSCHEDULE} = 1 $<$$<$ 3 |
| 56 |
\} |
| 57 |
\begin{CompactList}\small\item\em Stream creation options. \item\end{CompactList}\item |
| 58 |
enum \{ \par |
| 59 |
\hyperlink{group__stream_gga3a10}{PEAK\_\-STREAM\_\-EVT\_\-NONE} = 0, |
| 60 |
\par |
| 61 |
\hyperlink{group__stream_gga3a11}{PEAK\_\-STREAM\_\-EVT\_\-OPEN}, |
| 62 |
\par |
| 63 |
\hyperlink{group__stream_gga3a12}{PEAK\_\-STREAM\_\-EVT\_\-ACCEPT}, |
| 64 |
\par |
| 65 |
\hyperlink{group__stream_gga3a13}{PEAK\_\-STREAM\_\-EVT\_\-READ}, |
| 66 |
\par |
| 67 |
\hyperlink{group__stream_gga3a14}{PEAK\_\-STREAM\_\-EVT\_\-WRITE}, |
| 68 |
\par |
| 69 |
\hyperlink{group__stream_gga3a15}{PEAK\_\-STREAM\_\-EVT\_\-END}, |
| 70 |
\par |
| 71 |
\hyperlink{group__stream_gga3a16}{PEAK\_\-STREAM\_\-EVT\_\-ERROR}, |
| 72 |
\par |
| 73 |
\hyperlink{group__stream_gga3a17}{PEAK\_\-STREAM\_\-EVT\_\-TIMEDOUT} |
| 74 |
\} |
| 75 |
\begin{CompactList}\small\item\em Types of event passed to your stream event callback function. \item\end{CompactList}\end{CompactItemize} |
| 76 |
|
| 77 |
|
| 78 |
\subsection{Typedef Documentation} |
| 79 |
\hypertarget{group__stream_ga1}{ |
| 80 |
\index{stream@{stream}!peak_stream_event_callback@{peak\_\-stream\_\-event\_\-callback}} |
| 81 |
\index{peak_stream_event_callback@{peak\_\-stream\_\-event\_\-callback}!stream@{stream}} |
| 82 |
\subsubsection[peak\_\-stream\_\-event\_\-callback]{\setlength{\rightskip}{0pt plus 5cm}typedef void($\ast$ \hyperlink{group__stream_ga1}{peak\_\-stream\_\-event\_\-callback})(\hyperlink{group__stream_ga0}{peak\_\-stream} s, int type, void $\ast$context)}} |
| 83 |
\label{group__stream_ga1} |
| 84 |
|
| 85 |
|
| 86 |
Stream client event callback. |
| 87 |
|
| 88 |
Defines a pointer to your notification callback function that handles interesting events that occur on a scheduled stream. |
| 89 |
|
| 90 |
\subsection{Enumeration Type Documentation} |
| 91 |
\hypertarget{group__stream_ga2}{ |
| 92 |
\subsubsection["@4]{\setlength{\rightskip}{0pt plus 5cm}anonymous enum}} |
| 93 |
\label{group__stream_ga2} |
| 94 |
|
| 95 |
|
| 96 |
Stream creation options. |
| 97 |
|
| 98 |
\begin{Desc} |
| 99 |
\item[Enumeration values: ]\par |
| 100 |
\begin{description} |
| 101 |
\index{PEAK_STREAM_OPT_DEFAULT@{PEAK\_\-STREAM\_\-OPT\_\-DEFAULT}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_OPT_DEFAULT@{PEAK\_\-STREAM\_\-OPT\_\-DEFAULT}}\item[{\em |
| 102 |
\hypertarget{group__stream_gga2a5}{ |
| 103 |
PEAK\_\-STREAM\_\-OPT\_\-DEFAULT} |
| 104 |
\label{group__stream_gga2a5} |
| 105 |
}]Default: SOCK\_\-STREAM socket (reliable stream), ie. TCP. \index{PEAK_STREAM_OPT_DGRAM@{PEAK\_\-STREAM\_\-OPT\_\-DGRAM}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_OPT_DGRAM@{PEAK\_\-STREAM\_\-OPT\_\-DGRAM}}\item[{\em |
| 106 |
\hypertarget{group__stream_gga2a6}{ |
| 107 |
PEAK\_\-STREAM\_\-OPT\_\-DGRAM} |
| 108 |
\label{group__stream_gga2a6} |
| 109 |
}]UDP socket stream (not a reliable stream). \index{PEAK_STREAM_OPT_LISTEN@{PEAK\_\-STREAM\_\-OPT\_\-LISTEN}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_OPT_LISTEN@{PEAK\_\-STREAM\_\-OPT\_\-LISTEN}}\item[{\em |
| 110 |
\hypertarget{group__stream_gga2a7}{ |
| 111 |
PEAK\_\-STREAM\_\-OPT\_\-LISTEN} |
| 112 |
\label{group__stream_gga2a7} |
| 113 |
}]Listening socket stream. Will use the address argument as the local address (where to bind). \index{PEAK_STREAM_OPT_LINEMODE@{PEAK\_\-STREAM\_\-OPT\_\-LINEMODE}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_OPT_LINEMODE@{PEAK\_\-STREAM\_\-OPT\_\-LINEMODE}}\item[{\em |
| 114 |
\hypertarget{group__stream_gga2a8}{ |
| 115 |
PEAK\_\-STREAM\_\-OPT\_\-LINEMODE} |
| 116 |
\label{group__stream_gga2a8} |
| 117 |
}]Line mode, useful for line-based text streams; the callback is called for every line received. \index{PEAK_STREAM_OPT_AUTOSCHEDULE@{PEAK\_\-STREAM\_\-OPT\_\-AUTOSCHEDULE}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_OPT_AUTOSCHEDULE@{PEAK\_\-STREAM\_\-OPT\_\-AUTOSCHEDULE}}\item[{\em |
| 118 |
\hypertarget{group__stream_gga2a9}{ |
| 119 |
PEAK\_\-STREAM\_\-OPT\_\-AUTOSCHEDULE} |
| 120 |
\label{group__stream_gga2a9} |
| 121 |
}]Auto schedule, avoid a call to peak\_\-stream\_\-schedule. Useful for accepted socket. \end{description} |
| 122 |
\end{Desc} |
| 123 |
|
| 124 |
\hypertarget{group__stream_ga3}{ |
| 125 |
\subsubsection["@5]{\setlength{\rightskip}{0pt plus 5cm}anonymous enum}} |
| 126 |
\label{group__stream_ga3} |
| 127 |
|
| 128 |
|
| 129 |
Types of event passed to your stream event callback function. |
| 130 |
|
| 131 |
\begin{Desc} |
| 132 |
\item[Enumeration values: ]\par |
| 133 |
\begin{description} |
| 134 |
\index{PEAK_STREAM_EVT_NONE@{PEAK\_\-STREAM\_\-EVT\_\-NONE}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_EVT_NONE@{PEAK\_\-STREAM\_\-EVT\_\-NONE}}\item[{\em |
| 135 |
\hypertarget{group__stream_gga3a10}{ |
| 136 |
PEAK\_\-STREAM\_\-EVT\_\-NONE} |
| 137 |
\label{group__stream_gga3a10} |
| 138 |
}]Never used. \index{PEAK_STREAM_EVT_OPEN@{PEAK\_\-STREAM\_\-EVT\_\-OPEN}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_EVT_OPEN@{PEAK\_\-STREAM\_\-EVT\_\-OPEN}}\item[{\em |
| 139 |
\hypertarget{group__stream_gga3a11}{ |
| 140 |
PEAK\_\-STREAM\_\-EVT\_\-OPEN} |
| 141 |
\label{group__stream_gga3a11} |
| 142 |
}]Open event. The stream is now open (connection established). \index{PEAK_STREAM_EVT_ACCEPT@{PEAK\_\-STREAM\_\-EVT\_\-ACCEPT}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_EVT_ACCEPT@{PEAK\_\-STREAM\_\-EVT\_\-ACCEPT}}\item[{\em |
| 143 |
\hypertarget{group__stream_gga3a12}{ |
| 144 |
PEAK\_\-STREAM\_\-EVT\_\-ACCEPT} |
| 145 |
\label{group__stream_gga3a12} |
| 146 |
}]Accept event. A new stream can be created using \hyperlink{group__stream__common_ga32}{peak\_\-stream\_\-accept\_\-create()}. \index{PEAK_STREAM_EVT_READ@{PEAK\_\-STREAM\_\-EVT\_\-READ}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_EVT_READ@{PEAK\_\-STREAM\_\-EVT\_\-READ}}\item[{\em |
| 147 |
\hypertarget{group__stream_gga3a13}{ |
| 148 |
PEAK\_\-STREAM\_\-EVT\_\-READ} |
| 149 |
\label{group__stream_gga3a13} |
| 150 |
}]Read event. There's something to read on the stream. |
| 151 |
|
| 152 |
Until you don't really read it, you won't be notified again with this event type. \index{PEAK_STREAM_EVT_WRITE@{PEAK\_\-STREAM\_\-EVT\_\-WRITE}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_EVT_WRITE@{PEAK\_\-STREAM\_\-EVT\_\-WRITE}}\item[{\em |
| 153 |
\hypertarget{group__stream_gga3a14}{ |
| 154 |
PEAK\_\-STREAM\_\-EVT\_\-WRITE} |
| 155 |
\label{group__stream_gga3a14} |
| 156 |
}]Write event. You can efficiently write on the stream NOW. |
| 157 |
|
| 158 |
Until you don't really write something, you won't be notified again with this event type. \index{PEAK_STREAM_EVT_END@{PEAK\_\-STREAM\_\-EVT\_\-END}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_EVT_END@{PEAK\_\-STREAM\_\-EVT\_\-END}}\item[{\em |
| 159 |
\hypertarget{group__stream_gga3a15}{ |
| 160 |
PEAK\_\-STREAM\_\-EVT\_\-END} |
| 161 |
\label{group__stream_gga3a15} |
| 162 |
}]End of stream event. No further bytes can be read/written. |
| 163 |
|
| 164 |
You should release the stream with \hyperlink{group__alloc_ga7}{peak\_\-release()}. \index{PEAK_STREAM_EVT_ERROR@{PEAK\_\-STREAM\_\-EVT\_\-ERROR}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_EVT_ERROR@{PEAK\_\-STREAM\_\-EVT\_\-ERROR}}\item[{\em |
| 165 |
\hypertarget{group__stream_gga3a16}{ |
| 166 |
PEAK\_\-STREAM\_\-EVT\_\-ERROR} |
| 167 |
\label{group__stream_gga3a16} |
| 168 |
}]An error occured on the stream's connection. |
| 169 |
|
| 170 |
You should release the stream with \hyperlink{group__alloc_ga7}{peak\_\-release()}. \index{PEAK_STREAM_EVT_TIMEDOUT@{PEAK\_\-STREAM\_\-EVT\_\-TIMEDOUT}!stream@{stream}}\index{stream@{stream}!PEAK_STREAM_EVT_TIMEDOUT@{PEAK\_\-STREAM\_\-EVT\_\-TIMEDOUT}}\item[{\em |
| 171 |
\hypertarget{group__stream_gga3a17}{ |
| 172 |
PEAK\_\-STREAM\_\-EVT\_\-TIMEDOUT} |
| 173 |
\label{group__stream_gga3a17} |
| 174 |
}]Stream's event timed out. |
| 175 |
|
| 176 |
Sent only when you enable stream's event timeout checking with \hyperlink{group__stream__common_ga53}{peak\_\-stream\_\-set\_\-timeout()}. You might release the stream with \hyperlink{group__alloc_ga7}{peak\_\-release()}. If you ignore it, another event of type {\em PEAK\_\-STREAM\_\-EVT\_\-TIMEDOUT\/} will be sent after {\tt timeout} seconds as defined in \hyperlink{group__stream__common_ga53}{peak\_\-stream\_\-set\_\-timeout()}. \end{description} |
| 177 |
\end{Desc} |
| 178 |
|
