summaryrefslogtreecommitdiff
path: root/doc/texinfo/url.texi
blob: c743dcd168109e49e79b88b4bd25e4889eca0cad (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999-2020 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************

@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.

@subsubheading POP3
The POP URL scheme contains a POP server, optional port number
and the authentication mechanism. The general form is

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

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

@smallexample
@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}
@end smallexample

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

@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.

@subsubheading IMAP
The IMAP URL scheme contains an IMAP server, optional port number
and the authentication mechanism. The general form is

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

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

@smallexample
@indicateurl{imap://obelix@@imap.gaulois.org}
@indicateurl{imap://asterix;AUTH=*@@imap.france.com}
@indicateurl{imap://asterix:potion@@imap.france.com}
@end smallexample

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

@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.

@subsubheading File

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

@smallexample
@group
@indicateurl{file://@var{path}}
@indicateurl{file://var/mail/user}
@indicateurl{file://home/obelix/Mail}
@end group
@end smallexample

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

@smallexample
@group
@indicateurl{mmdf://@var{path}}
@indicateurl{mh://@var{path}}
@end group
@end smallexample

@subsubheading Mailto

After setting a mailer, @indicateurl{mailto:} is used to tell the mailer where
and to whom the message is for.

@smallexample
@indicateurl{mailto://@var{hostname}}
@end smallexample

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

@smallexample
@indicateurl{mailto://bug-mailutils@@gnu.org?body=subscribe}
@indicateurl{mailto://bug-mailutils@@gnu.org?Subject=hello&body=subscribe}
@end smallexample

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

@c
@c URL Functions
@c

@subsubheading URL Functions

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

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

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

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

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:

@smallexample
@group
url =
    scheme ":" [ "//"

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

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

    [ ( "/" @var{urlpath} ) | ( "?" @var{query} ) ] ]
@end group
@end smallexample

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

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

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

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

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

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

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

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

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

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

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

@deftypefun  int mu_url_is_same_scheme (mu_url_t, mu_url_t)
@end deftypefun

@deftypefun  int mu_url_is_same_user (mu_url_t, mu_url_t)
@end deftypefun

@deftypefun  int mu_url_is_same_path (mu_url_t, mu_url_t)
@end deftypefun

@deftypefun  int mu_url_is_same_host (mu_url_t, mu_url_t)
@end deftypefun

@deftypefun  int mu_url_is_same_port (mu_url_t, mu_url_t)
@end deftypefun

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

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

@subsubheading Example
@smallexample
@include url-parse.inc
@end smallexample

Return to:

Send suggestions and report system problems to the System administrator.