docs/ipc.tex

   1 \documentclass{article}
   2
   3 \newcounter{paramc}
   4 \newenvironment{paramlist}
   5 {\begin{list}{\bfseries\upshape \hspace{2em}Parameter \arabic{paramc}:}
   6 {\usecounter{paramc}\setlength{\parsep}{0.0ex}\setlength}}
   7 {\end{list}}
   8
   9 \newcommand{\ipcmsg}[1]{{\raggedleft\bfseries\upshape #1}}
  10
  11 \begin{document}
  12
  13 \section{Conventions}
  14
  15 When describing the comunication examples between two process we will
  16 define one process as a client (requesting a service) as the server,
  17 the format to describe a message will be the following:
  18
  19 \begin{verbatim}
  20 C: message name: parameter 1 ; parameter 2 ; parameter 3
  21 S: message name: parameter 1 ; parameter 2 ; parameter 3
  22 \end{verbatim}
  23
  24 Where C is client and S server.
  25
  26 \section{Common Messages}
  27
  28 \ipcmsg{ok}
  29
  30 A positive response to another mensage, should include a return value.
  31
  32 \begin{paramlist}
  33 \item Return Value
  34 \end{paramlist}
  35
  36 \ipcmsg{error}
  37
  38 An error message.
  39
  40 \begin{paramlist}
  41 \item Message
  42 \end{paramlist}
  43
  44 \section{Authentication Server}
  45 \subsection{Messages}
  46
  47 \ipcmsg{verify}
  48
  49 Verify if a user exist, will return "ok" is the user
  50 exist, error otherwise.
  51
  52 \begin{paramlist}
  53 \item Username
  54 \end{paramlist}
  55
  56 \ipcmsg{auth}
  57
  58 Will authenticate a given user, will return ok if the
  59 user and password are right, error otherwise.
  60
  61 \begin{paramlist}
  62 \item Username
  63 \item Password
  64 \end{paramlist}
  65
  66 \section{Mail Queue Server}
  67
  68 \subsection{Comunication Examples}
  69 \subsubsection{Adding a message to a queue}
  70
  71 With a given queue named "incoming" we will push a message to it,
  72 where C is the client and QS is the queue server:
  73
  74 \begin{verbatim}
  75 C:  slot: incoming
  76 QS: ok: /tmp/fmain/queues/incoming/212214962143124030
  77 C:  push: incoming ; /tmp/fmain/queues/incoming/212214962143124030
  78 QS: ok
  79 \end{verbatim}
  80
  81 \subsubsection{Getting a message from a queue}
  82
  83 With a given queue named "incoming" we will pop a message from it,
  84 where C is the client and QS is the queue server:
  85
  86 \begin{verbatim}
  87 C:  pop: incoming
  88 QS: ok: /tmp/fmain/queues/incoming/212214962143124030
  89 \end{verbatim}
  90
  91 \subsubsection{Subscribing to a queue}
  92
  93 With a given queue named "incoming" we will subscribe to it,
  94 where C is the client and QS is the queue server:
  95
  96 \begin{verbatim}
  97 C:  subscribe: incoming ; socket://127.0.0.1:14001
  98 QS: ok
  99 \end{verbatim}
 100
 101 Once the client is subscribed and there is new messages in the queue,
 102 the queue server will connect back to the client and send the message
 103 "alert", then the client may pop messages till it receives the error
 104 message:
 105
 106 \begin{verbatim}
 107 QS: alert: incoming
 108 C: pop: incoming
 109 QS: ok: /tmp/fmain/queues/incoming/212214962143124030
 110 C: pop: incoming
 111 QS: error
 112 \end{verbatim}
 113
 114 \subsection{Messages}
 115
 116 \ipcmsg{slot}
 117
 118 Request a slot from the message queue, it will send
 119 back an OK response with the filename to use, this
 120 filename will be the identifier the requested slot.
 121
 122 After writing the data into the file you must send back
 123 a the finishing message "push", in order to move the
 124 message to the queue.
 125
 126 \begin{paramlist}
 127 \item Queue Name
 128 \end{paramlist}
 129
 130 \ipcmsg{push}
 131
 132 Tell the queue server that it can move a given message to
 133 the queue, this means that we finished writing the data to
 134 the file and it is closed.
 135
 136 \begin{paramlist}
 137 \item Queue Name
 138 \item Filaname
 139 \end{paramlist}
 140
 141 \ipcmsg{pop}
 142
 143 Retrieve the next message in the queue, it will return an OK
 144 message with the filename.
 145
 146 \begin{paramlist}
 147 \item Queue Name
 148 \end{paramlist}
 149
 150 \ipcmsg{subscribe}
 151
 152 Subscribe to a message queue, the subscriber will receive alerts
 153 when there is new messages in the queue.
 154
 155 \begin{paramlist}
 156 \item Queue Name
 157 \item IPC Callback String
 158 \end{paramlist}
 159
 160 \ipcmsg{unsuscribe}
 161
 162 Remove subscription to a queue. The IPC Callback String should
 163 be exactly the same as given on subscription.
 164
 165 \begin{paramlist}
 166 \item Queue Name
 167 \item IPC Callback String
 168 \end{paramlist}
 169
 170 \section{Mailbox Server}
 171
 172 \subsection{Comunication Examples}
 173
 174 \subsubsection{Listing a user mailbox}
 175
 176 Give a mailbox server MS and a client C:
 177
 178 \begin{verbatim}
 179 C: list: user_john
 180 MS: ok: 2
 181 MS: mailinfo: 1 ; 120
 182 MS: mailinfo: 2 ; 300
 183 MS: ok
 184 \end{verbatim}
 185
 186 \subsection{Messages}
 187
 188 \ipcmsg{list}
 189
 190 It will return ok message with the amount of emails
 191 for a given user, after that it will push n "mailinfo"
 192 message. On failture it will return error.
 193
 194 \begin{paramlist}
 195 \item Username
 196 \end{paramlist}
 197
 198 \ipcmsg{mailinfo}
 199
 200 Return message with a given email detail.
 201
 202 \begin{paramlist}
 203 \item Message Number
 204 \item Message Size (in octets)
 205 \end{paramlist}
 206
 207 \ipcmsg{store}
 208
 209 Store an email, it will return ok if successful and
 210 begin using raw operations till read 'Data Length'
 211 bytes.
 212
 213 \begin{paramlist}
 214 \item To
 215 \item Recipent
 216 \item Data Length
 217 \end{paramlist}
 218
 219 \ipcmsg{retr}
 220
 221 Retrieve an email for a given user. Should
 222 return ok with the size of the email if the
 223 email number is valid and then it will
 224 start sending the email using raw operations.
 225 If the email number is invalid will return error.
 226
 227 \begin{paramlist}
 228 \item Username
 229 \item Message Number
 230 \end{paramlist}
 231
 232 \ipcmsg{dele}
 233
 234 Delete an email for a given user. It will return
 235 ok if the operation was sucessful, error otherwise
 236 (when the message doesen't exist.
 237
 238 \begin{paramlist}
 239 \item Username
 240 \item Message Number
 241 \end{paramlist}
 242
 243 \end{document}