auth.texi

Authenticator.

+Mailboxes and Mailers provide a way to authenticate when the URL does not
+contain enough information.  The default action is to call function
+@code{auth_authenticate} who will get the @emph{user} and @emph{passwd}
+if not set, this function can be override by a custom method.
+
+@section Helper Funtions
+@deftypefun int auth_set_user (auth_t @var{auth}, const char *@var{user})
+Set the @var{user} to field value.
+@end deftypefun
+
+@deftypefun int auth_set_passwd (auth_t @var{auth}, const char *@var{passwd})
+Set the @var{passwd} to field value.
+@end deftypefun
+
+@deftypefun int auth_set_authenticate (auth_t @var{auth}, int *(authenticate)(auth_t, const char **user, const char **passwd)
+Set Override the authentification function.  If NULL authentication is
+disabled.  If *@var{user} and *@var{passwd} are not NULL, they should be
+@code{free(3)} before setting new values.
+@end deftypefun
+
+To copy new email from an FTP server,  lets suppose that we've register an
+ftp mailbox type.
+
+@example
+#include <mailutils.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+int main ()
+@{
+  mailbox_t ftp;
+  mailbox_t local;
+  auth_t auth;
+  size_t i, count;
+
+  /* assume that  ftp:// was register see @code{mailbox_add_type} */
+  if (mailbox_init (&local, "file:///home/thomasf/Mail/remote, 0) != 0
+      || mailbox_init (&ftp, "ftp://qnx.com/var/mail/thomasf, 0) != 0)
+    @{
+        fprintf (stderr, "Fail to init remote ftp mail\n");
+        exit (EXIT_FAILURE);
+    @}
+
+  mailbox_get_auth (ftp, &auth);
+  auth_set_user (auth, "thomasf");
+  auth_set_passwd (auth, "thomasf@@qnx.com");
+
+  if (mailbox_open (ftp, MU_MB_RDONLY) != 0
+      || mailbox_open (local, MU_MB_APPEND | MU_MB_CREAT) != 0)
+    @{
+        fprintf (stderr, "Fail to open remote ftp mail\n");
+        exit (EXIT_FAILURE);
+    @}
+
+   count = mailbox_count (ftp);
+   for (i = 1; i <= count; i++)
+    @{
+       mailbox_get_message (ftp, i, &message);
+       if (message_is_new (messsage))
+         @{
+            printf ("Appending message %d\n", i)
+            mailbox_append_message (local, message, 1);
+         @}
+    @}
+
+   mailbox_close (local);
+   mailbox_close (ftp);
+
+   return 0;
+@}
+
+@end example