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