Blame view

doc/texinfo/url.texi 6.8 KB
1
@c This is part of the GNU Mailutils manual.
2
@c Copyright (C) 1999-2004, 2006-2007, 2010-2012, 2014-2016 Free
3
@c Software Foundation, Inc.
4 5
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
6 7 8 9 10 11

@comment See rfc2368, rfc2369, rfc2384
A mailbox or a mailer can be described in a URL, the string will contain the
necessary information to initialize @code{mailbox_t}, or @code{mailer_t}
properly.

Sergey Poznyakoff authored
12
@subsubheading POP3
13
The POP URL scheme contains a POP server, optional port number
14
and the authentication mechanism. The general form is
15

16
@smallexample
17
@group
Sergey Poznyakoff authored
18
@indicateurl{pop://[@var{user}[;AUTH=@var{auth}]@@]@var{host}[:@var{port}]}
19
 or
Sergey Poznyakoff authored
20
@indicateurl{pop://[@var{user}[:@var{passwd}]@@]@var{host}[:@var{port}]}
21
@end group
22
@end smallexample
23 24

If @emph{:port} is omitted the default value is 110. Different forms of
25
authentication can be specified with @emph{;AUTH=@var{type}}.
26 27 28
The special string @emph{;AUTH=*} indicates that the client will use
a default scheme base on the capability of the server.

29
@smallexample
Sergey Poznyakoff authored
30 31 32 33 34
@indicateurl{pop://obelix@@gaulois.org}
@indicateurl{pop://asterix;AUTH=*@@france.com}
@indicateurl{pop://falbala;AUTH=+APOP@@france.com}
@indicateurl{pop://obelix;AUTH=+APOP@@village.gaulois.org:2000}
@indicateurl{pop://obelix:menhir@@village.gaulois.org:2000}
35
@end smallexample
36

37
For more complete information see @cite{RFC 2368}.
38

39 40 41 42 43 44 45 46 47 48 49 50 51 52
@subsubheading POP3S (POP3 Over SSL)
The POP3S URL scheme contains a POP server over SSL, optional port
number and the authentication mechanism. The general form is

@smallexample
@group
@indicateurl{pops://[@var{user}[;AUTH=@var{auth}]@@]@var{host}[:@var{port}]}
 or
@indicateurl{pops://[@var{user}[:@var{passwd}]@@]@var{host}[:@var{port}]}
@end group
@end smallexample

If @emph{:port} is omitted the default value is 995.

Sergey Poznyakoff authored
53
@subsubheading IMAP
54
The IMAP URL scheme contains an IMAP server, optional port number
55
and the authentication mechanism. The general form is
56

57
@smallexample
58
@group
Sergey Poznyakoff authored
59
@indicateurl{imap://[@var{user}[;AUTH=@var{type}]]@@@var{host}[:@var{port}][/@var{mailbox}]}
60
 or
Sergey Poznyakoff authored
61
@indicateurl{imap://[@var{user}[:@var{passwd}]]@@@var{host}[:@var{port}][/@var{mailbox}]}
62
@end group
63
@end smallexample
64

65 66
If @emph{:port} is omitted the default value is 143. Different forms of
authentication can be specified with @emph{;AUTH=@var{type}}.
67 68 69
The special string @emph{;AUTH=*} indicates that the client will use
a default scheme base on the capability of the server.

70
@smallexample
Sergey Poznyakoff authored
71 72 73
@indicateurl{imap://obelix@@imap.gaulois.org}
@indicateurl{imap://asterix;AUTH=*@@imap.france.com}
@indicateurl{imap://asterix:potion@@imap.france.com}
74
@end smallexample
75

76
For more complete information see @cite{RFC 2192}.
77

78 79 80 81 82 83 84 85 86 87 88 89 90 91
@subsubheading IMAPS (IMAP Over SSL)
The IMAPS URL scheme contains an IMAP server over SSL, optional port
number and the authentication mechanism. The general form is

@smallexample
@group
@indicateurl{imaps://[@var{user}[;AUTH=@var{type}]]@@@var{host}[:@var{port}][/@var{mailbox}]}
 or
@indicateurl{imaps://[@var{user}[:@var{passwd}]]@@@var{host}[:@var{port}][/@var{mailbox}]}
@end group
@end smallexample

If @emph{:port} is omitted the default value is 993.

Sergey Poznyakoff authored
92
@subsubheading File
93

94
Local folder should be handle by this URL. It is preferable to let
95 96 97
the mailbox recognize the type of mailbox and take the appropriate
action.

98
@smallexample
99
@group
Sergey Poznyakoff authored
100 101 102
@indicateurl{file://@var{path}}
@indicateurl{file://var/mail/user}
@indicateurl{file://home/obelix/Mail}
103
@end group
104
@end smallexample
105 106

For MMDF, MH local mailboxes URLs are provided,  but it is preferable to
Sergey Poznyakoff authored
107
use @indicateurl{file://@var{path}} and let the library figure out which one.
108

109
@smallexample
110
@group
Sergey Poznyakoff authored
111 112
@indicateurl{mmdf://@var{path}}
@indicateurl{mh://@var{path}}
113
@end group
114
@end smallexample
115

Sergey Poznyakoff authored
116
@subsubheading Mailto
117

Sergey Poznyakoff authored
118
After setting a mailer, @indicateurl{mailto:} is used to tell the mailer where
119 120
and to whom the message is for.

121
@smallexample
Sergey Poznyakoff authored
122
@indicateurl{mailto://@var{hostname}}
123
@end smallexample
124 125 126 127

Mailto can be used to generate short messages, for example to subscribe
to mailing lists.

128
@smallexample
Sergey Poznyakoff authored
129 130
@indicateurl{mailto://bug-mailutils@@gnu.org?body=subscribe}
@indicateurl{mailto://bug-mailutils@@gnu.org?Subject=hello&body=subscribe}
131
@end smallexample
132

133
For more complete information see @cite{RFC 2368}.
134

135 136 137 138
@c
@c URL Functions
@c

Sergey Poznyakoff authored
139
@subsubheading URL Functions
140 141 142

Helper functions are provided to retrieve and set the @emph{URL} fields.

143
@deftypefun  int mu_url_create (mu_url_t *@var{url}, const char *@var{name})
144
Create the url data structure, but do not parse it.
145 146
@end deftypefun

147
@deftypefun void mu_url_destroy (mu_url_t *@var{url})
148
Destroy the url and free its resources.
149 150
@end deftypefun

151
@deftypefun  int mu_url_parse (mu_url_t)
152 153
Parses the url, after calling this the get functions can be called.

154 155
The syntax, condensed from @cite{RFC 1738}, and extended with the ;auth=
of @cite{RFC 2384} (for POP) and @cite{RFC 2192} (for IMAP) is:
156

157
@smallexample
158
@group
159
url =
160
    scheme ":" [ "//"
161

162
    [ @var{user} [ ( ":" @var{password} ) | ( ";auth=" @var{auth} ) ] "@@" ]
163

164
    @var{host} [ ":" @var{port} ]
165

166 167
    [ ( "/" @var{urlpath} ) | ( "?" @var{query} ) ] ]
@end group
168
@end smallexample
169 170 171

This is a generalized URL syntax, and may not be exactly appropriate
for any particular scheme.
172 173
@end deftypefun

174
@deftypefun  int mu_url_get_scheme (const mu_url_t, char *, size_t, size_t *)
175 176
@end deftypefun

177
@deftypefun  int mu_url_get_user (const mu_url_t, char *, size_t, size_t *)
178 179
@end deftypefun

180
@deftypefun  int mu_url_get_passwd (const mu_url_t, char *, size_t, size_t *)
181
@end deftypefun
182

183
@deftypefun  int mu_url_get_auth (const mu_url_t, char *, size_t, size_t *)
184 185
@end deftypefun

186
@deftypefun  int mu_url_get_host (const mu_url_t, char *, size_t, size_t *)
187 188
@end deftypefun

189
@deftypefun  int mu_url_get_port (const mu_url_t, unsigned *)
190 191
@end deftypefun

192
@deftypefun  int mu_url_get_path (const mu_url_t, char *, size_t, size_t *)
193 194
@end deftypefun

195
@deftypefun  int mu_url_get_query (const mu_url_t, char *, size_t, size_t *)
196 197
@end deftypefun

198
@deftypefun  {const char*} mu_url_to_string (const mu_url_t)
199 200
@end deftypefun

201
@deftypefun  int mu_url_is_scheme (mu_url_t, const char *@var{scheme})
202 203
@end deftypefun

204
@deftypefun  int mu_url_is_same_scheme (mu_url_t, mu_url_t)
205 206
@end deftypefun

207
@deftypefun  int mu_url_is_same_user (mu_url_t, mu_url_t)
208 209
@end deftypefun

210
@deftypefun  int mu_url_is_same_path (mu_url_t, mu_url_t)
211 212
@end deftypefun

213
@deftypefun  int mu_url_is_same_host (mu_url_t, mu_url_t)
214 215
@end deftypefun

216
@deftypefun  int mu_url_is_same_port (mu_url_t, mu_url_t)
217 218
@end deftypefun

219
@deftypefun {char *} mu_url_decode (const char *@var{string})
220
Decodes an @cite{RFC 1738} encoded string, returning the decoded string
221 222
in allocated memory. If the string is not encoded, this degenerates to
a @code{strdup()}.
223 224
@end deftypefun

225
@deftypefun  int mu_url_is_ticket (mu_url_t @var{ticket}, mu_url_t @var{url})
226 227
@end deftypefun

Sergey Poznyakoff authored
228
@subsubheading Example
229
@smallexample
230
@include url-parse.inc
231
@end smallexample