1 PACKAGE utl_http AUTHID CURRENT_USER IS
2
3 /******************************************************************
4
5 The UTL_HTTP package makes Hypertext Transfer Protocol (HTTP) callouts
6 from SQL and PL/SQL. It can be used to access data on the Internet over
7 the HTTP protocol.
8
9 The package contains a set of API that enables users to write PL/SQL
10 programs that communicate with Web (HTTP) servers. It also contains a
11 function that can be used in SQL queries. Besides the HTTP protocol, it
12 also supports the HTTP protocol over the Secured Socket Layer protocol (SSL),
13 also known as HTTPS, directly or via a HTTP proxy. Other Internet-related
14 data-access protocols (such as the File Transfer Protocol (FTP) or
15 the Gopher protocol) are also supported via a HTTP proxy server that
16 supports those protocols.
17
18 When the package fetches data from a Web site using the HTTPS protocol,
19 it requires an Oracle wallet to be set up properly by Oracle Wallet Manager.
20 Non-HTTPS fetches do not require an Oracle wallet.
21
22 The API is divided into a number of categories. The session API manipulates
23 configurations pertaining to the package within a database user session.
24 The request API begins a new HTTP request, manipulates its attributes,
25 and sends information to the Web server. The response API returns the
26 attributes of the response and receives information the response data
27 from the Web server. The cookies API manipulates the HTTP cookies maintained
28 by the package within the database user session. The persistent connection
29 API manipulates the persistent connections maintained by the package. There
30 are also two simple functions that allow users to fetch a Web page by
31 a single function call.
32
33 The following is an example that illustrate the use of the session,
34 request, and response API to pretend to be the Netscape brower to fetch
35 a Web page.
36
37 SET serveroutput ON SIZE 40000
38
39 DECLARE
40 req utl_http.req;
41 resp utl_http.resp;
42 value VARCHAR2(1024);
43 BEGIN
44
45 utl_http.set_proxy('proxy.it.my-company.com', 'my-company.com');
46
47 req := utl_http.begin_request('http://www-hr.corp.my-company.com');
48 utl_http.set_header(req, 'User-Agent', 'Mozilla/4.0');
49 resp := utl_http.get_response(req);
50 LOOP
51 utl_http.read_line(resp, value, TRUE);
52 dbms_output.put_line(value);
53 END LOOP;
54 utl_http.end_response(resp);
55 EXCEPTION
56 WHEN utl_http.end_of_body THEN
57 utl_http.end_response(resp);
58 END;
59
60 The following is another example that illustrates how to use the simple
61 API to fetch a Web page in SQL (only the first 2000 bytes will be returned).
62
63 SVRMGR> select utl_http.request('http://www.oracle.com/')
64 2 from dual;
65 UTL_HTTP.REQUEST('HTTP://WWW.ORACLE.COM/')
66 ----------------------------------------------------------
67 <html>
68 <head><title>Oracle Corporation Home Page</title>
69 <!--changed Jan. 16, 19
70 1 row selected.
71
72 Here is another example that illustrates how to use the other simple API
73 to fetch the complete Web page:
74
75 set serveroutput on
76
77 declare
78 x utl_http.html_pieces;
79 len pls_integer;
80 begin
81 x := utl_http.request_pieces('http://www.oracle.com/', 100);
82 dbms_output.put_line(x.count || ' pieces were retrieved.');
83 dbms_output.put_line('with total length ');
84 len := 0;
85 for i in 1..x.count loop
86 len := len + length(x(i));
87 end loop;
88 dbms_output.put_line(len);
89 end;
90
91 Here is the output:
92
93 Statement processed.
94 4 pieces were retrieved.
95 with total length
96 7687
97
98 ***********************************************************************/
99
100 -- The HTTP protocol versions that can be used in the function begin_request
101 HTTP_VERSION_1_0 CONSTANT VARCHAR2(64) := 'HTTP/1.0'; -- HTTP 1.0
102 HTTP_VERSION_1_1 CONSTANT VARCHAR2(64) := 'HTTP/1.1'; -- HTTP 1.1
103
104 -- The default TCP/IP port numbers that a HTTP server listens
105 DEFAULT_HTTP_PORT CONSTANT PLS_INTEGER := 80; -- HTTP server or proxy server
106 DEFAULT_HTTPS_PORT CONSTANT PLS_INTEGER := 443; -- HTTPS server
107
108 -- HTTP status codes of a HTTP response as defined in HTTP 1.1
109 HTTP_CONTINUE CONSTANT PLS_INTEGER := 100;
110 HTTP_SWITCHING_PROTOCOLS CONSTANT PLS_INTEGER := 101;
111 HTTP_OK CONSTANT PLS_INTEGER := 200;
112 HTTP_CREATED CONSTANT PLS_INTEGER := 201;
113 HTTP_ACCEPTED CONSTANT PLS_INTEGER := 202;
114 HTTP_NON_AUTHORITATIVE_INFO CONSTANT PLS_INTEGER := 203;
115 HTTP_NO_CONTENT CONSTANT PLS_INTEGER := 204;
116 HTTP_RESET_CONTENT CONSTANT PLS_INTEGER := 205;
117 HTTP_PARTIAL_CONTENT CONSTANT PLS_INTEGER := 206;
118 HTTP_MULTIPLE_CHOICES CONSTANT PLS_INTEGER := 300;
119 HTTP_MOVED_PERMANENTLY CONSTANT PLS_INTEGER := 301;
120 HTTP_FOUND CONSTANT PLS_INTEGER := 302;
121 HTTP_SEE_OTHER CONSTANT PLS_INTEGER := 303;
122 HTTP_NOT_MODIFIED CONSTANT PLS_INTEGER := 304;
123 HTTP_USE_PROXY CONSTANT PLS_INTEGER := 305;
124 HTTP_TEMPORARY_REDIRECT CONSTANT PLS_INTEGER := 307;
125 HTTP_BAD_REQUEST CONSTANT PLS_INTEGER := 400;
126 HTTP_UNAUTHORIZED CONSTANT PLS_INTEGER := 401;
127 HTTP_PAYMENT_REQUIRED CONSTANT PLS_INTEGER := 402;
128 HTTP_FORBIDDEN CONSTANT PLS_INTEGER := 403;
129 HTTP_NOT_FOUND CONSTANT PLS_INTEGER := 404;
130 HTTP_NOT_ACCEPTABLE CONSTANT PLS_INTEGER := 406;
131 HTTP_PROXY_AUTH_REQUIRED CONSTANT PLS_INTEGER := 407;
132 HTTP_REQUEST_TIME_OUT CONSTANT PLS_INTEGER := 408;
133 HTTP_CONFLICT CONSTANT PLS_INTEGER := 409;
134 HTTP_GONE CONSTANT PLS_INTEGER := 410;
135 HTTP_LENGTH_REQUIRED CONSTANT PLS_INTEGER := 411;
136 HTTP_PRECONDITION_FAILED CONSTANT PLS_INTEGER := 412;
137 HTTP_REQUEST_ENTITY_TOO_LARGE CONSTANT PLS_INTEGER := 413;
138 HTTP_REQUEST_URI_TOO_LARGE CONSTANT PLS_INTEGER := 414;
139 HTTP_UNSUPPORTED_MEDIA_TYPE CONSTANT PLS_INTEGER := 415;
140 HTTP_REQ_RANGE_NOT_SATISFIABLE CONSTANT PLS_INTEGER := 416;
141 HTTP_EXPECTATION_FAILED CONSTANT PLS_INTEGER := 417;
142 HTTP_NOT_IMPLEMENTED CONSTANT PLS_INTEGER := 501;
143 HTTP_BAD_GATEWAY CONSTANT PLS_INTEGER := 502;
144 HTTP_SERVICE_UNAVAILABLE CONSTANT PLS_INTEGER := 503;
145 HTTP_GATEWAY_TIME_OUT CONSTANT PLS_INTEGER := 504;
146 HTTP_VERSION_NOT_SUPPORTED CONSTANT PLS_INTEGER := 505;
147
148 -- Exceptions
149 --
150 -- NOTES:
151 -- The partial_multibyte_char and transfer_timeout exceptions are
152 -- duplicates of the same exceptions as defined in the UTL_TCP package.
153 -- They are defined in this package so that the use of this package does not
154 -- require the knowledge of the UTL_TCP package. As those exceptions
155 -- are duplicates, an exception handle which catches the
156 -- partial_multibyte_char and transfer_timeout exceptions in this
157 -- package also catches those exceptions in the UTL_TCP package.
158 --
159 init_failed EXCEPTION; -- The UTL_HTTP pkg initialization failed
160 request_failed EXCEPTION; -- The HTTP request failed
161 bad_argument EXCEPTION; -- A bad argument was passed to an API
162 bad_url EXCEPTION; -- The URL is bad
163 protocol_error EXCEPTION; -- A HTTP protocol error occurred
164 unknown_scheme EXCEPTION; -- The scheme of the URL is unknown
165 header_not_found EXCEPTION; -- The HTTP header is not found
166 end_of_body EXCEPTION; -- The end of response body is reached
167 illegal_call EXCEPTION; -- The API call is illegal at this stage
168 http_client_error EXCEPTION; -- A 4xx response code is returned
169 http_server_error EXCEPTION; -- A 5xx response code is returned
170 too_many_requests EXCEPTION; -- Too many open requests or responses
171 partial_multibyte_char EXCEPTION; -- A partial multi-byte character found
172 transfer_timeout EXCEPTION; -- Transfer time-out occurred
173 network_access_denied EXCEPTION; -- Network access denied
174
175 PRAGMA EXCEPTION_INIT(init_failed, -29272);
176 PRAGMA EXCEPTION_INIT(request_failed, -29273);
177 PRAGMA EXCEPTION_INIT(bad_argument, -29261);
178 PRAGMA EXCEPTION_INIT(bad_url, -29262);
179 PRAGMA EXCEPTION_INIT(protocol_error, -29263);
180 PRAGMA EXCEPTION_INIT(unknown_scheme, -29264);
181 PRAGMA EXCEPTION_INIT(header_not_found, -29265);
182 PRAGMA EXCEPTION_INIT(end_of_body, -29266);
183 PRAGMA EXCEPTION_INIT(illegal_call, -29267);
184 PRAGMA EXCEPTION_INIT(http_client_error, -29268);
185 PRAGMA EXCEPTION_INIT(http_server_error, -29269);
186 PRAGMA EXCEPTION_INIT(too_many_requests, -29270);
187 PRAGMA EXCEPTION_INIT(partial_multibyte_char,-29275);
188 PRAGMA EXCEPTION_INIT(transfer_timeout, -29276);
189 PRAGMA EXCEPTION_INIT(network_access_denied, -24247);
190
191 -- VARCHAR2 table for returning HTML from request_pieces
192 TYPE html_pieces IS TABLE OF VARCHAR2(2000) INDEX BY BINARY_INTEGER;
193
194 -- A PL/SQL record type that represents a HTTP request
195 TYPE req IS RECORD (
196 url VARCHAR2(32767 byte), -- Requested URL
197 method VARCHAR2(64), -- Requested method
198 http_version VARCHAR2(64), -- Requested HTTP version
199 private_hndl PLS_INTEGER -- For internal use only
200 );
201
202 -- A PL/SQL record type that represents a HTTP response
203 TYPE resp IS RECORD (
204 status_code PLS_INTEGER, -- Response status code
205 reason_phrase VARCHAR2(256), -- Response reason phrase
206 http_version VARCHAR2(64), -- Response HTTP version
207 private_hndl PLS_INTEGER -- For internal use only
208 );
209 /* Note:
210 * - the "private_xxxx" field(s) in the req and resp record types are for
211 * internal use only and users should not try to modify them.
212 * - the HTTP information returned in the req and resp from the API
213 * begin_request and get_response are for read only. Changing the
214 * field values in the records has no effect to request or reesponse
215 * when making calls to the API in this package.
216 */
217
218 -- A PL/SQL record type that represents a HTTP cookie
219 TYPE cookie IS RECORD (
220 name VARCHAR2(256), -- Cookie name
221 value VARCHAR2(1024), -- Cookie value
222 domain VARCHAR2(256), -- Domain for which the cookie applies
223 expire TIMESTAMP WITH TIME ZONE, -- When should the cookie expire ?
224 path VARCHAR2(1024), -- Virtual path for which the cookie applies
225 secure BOOLEAN, -- Should the cookie be transferred by HTTPS only
226 version PLS_INTEGER, -- Cookie specification version
227 comment VARCHAR2(1024) -- Comments about this cookie
228 );
229 -- A PL/SQL table of cookies
230 TYPE cookie_table IS TABLE OF cookie INDEX BY BINARY_INTEGER;
231
232 -- A PL/SQL record type that represents the host name(s) and TCP/IP port
233 -- number(s) of a HTTP persistent connection that is maintained in
234 -- the current database session.
235 --
236 -- For a direct HTTP persistent connection to a Web server, the host and
237 -- port fields contain the host name and TCP/IP port number of the Web
238 -- server. The proxy_host and proxy_port fields are not set. For a HTTP
239 -- persistent connection that was previously used to connect to a Web
240 -- server via a proxy, the proxy_host and proxy_port fields contains
241 -- the host name and TCP/IP port number of the proxy server. The host
242 -- and port fields are not set, which indicates that the persistent
243 -- connection, while connected to a proxy server, is not bound to any
244 -- particular target Web server. As a matter of fact, a HTTP persistent
245 -- connection to a proxy server can be used to access any target Web server
246 -- to be accessed via the proxy.
247 --
248 -- The ssl field indicates if Secured Socket Layer (SSL) is being used in a
249 -- HTTP persistent connection or not. Note that a HTTPS request is a HTTP
250 -- request made over SSL. For a HTTPS (SSL) persistent connection connected
251 -- via a proxy, the host and port fields contain the host name and TCP/IP
252 -- port number of the target HTTPS Web server and the fields will always be
253 -- set. As a matter of fact, a HTTPS persistent connection to a HTTPS
254 -- Web server via a proxy server can only be reused to make another request
255 -- to the same target Web server.
256 --
257 TYPE connection IS RECORD (
258 host VARCHAR2(256), -- The host this persistent conn. is connected to
259 port PLS_INTEGER, -- The port this persistent conn. is connected to
260 proxy_host VARCHAR2(256), -- The proxy host this persistent conn. is
261 -- connected to
262 proxy_port PLS_INTEGER, -- The proxy port this persistent conn. is
263 -- connected to
264 ssl BOOLEAN -- Is this a SSL connection?
265 );
266 -- A PL/SQL table of persistent connections
267 TYPE connection_table IS TABLE OF connection INDEX BY BINARY_INTEGER;
268
269 -- A PL/SQL type that represents the key to a request context. A request
270 -- context is a context that holds a wallet and a cookie for private use
271 -- in making a HTTP request.
272 SUBTYPE request_context_key is PLS_INTEGER;
273
274 /*-------------------------- Session API ------------------------------*/
275 /* The following set of API manipulate the configuration and default
276 * behavior of this package when executing HTTP requests within a database
277 * user session. When a request is created, it inherits the default settings
278 * of the HTTP cookie support, follow-redirect, body character set,
279 * persistent-connection support, and transfer time-out of the current
280 * session. Those settings may be changed later by calling the request API.
281 * When a response is created for a request, it inherits those settings from
282 * the request. Only the body character set may be changed later by calling
283 * the response API.
284 */
285
286 /**
287 * Sets the proxy to be used for requests of the HTTP or other protocols,
288 * excluding those for hosts which belong to the domain specified in
289 * no_proxy_domains. proxy may include an optional TCP/IP port number
290 * at which the proxy server listens at. If the port is not specified for the
291 * proxy, port 80 is assumed.
292 *
293 * no_proxy_domains is a list of domains or hosts for which HTTP requests
294 * should be sent directly to the destination HTTP server instead of going
295 * through a proxy server. Optionally, a port number may be specified for
296 * each domain or host. If the port number is specified, the no-proxy
297 * restriction is only applied to the request at that port of the particular
298 * domain or host. . When no_proxy_domains is
299 * NULL and proxy is set, all requests go through the proxy. When proxy
300 * is not set, UTL_HTTP sends the requests to the target Web servers
301 * directly.
302 *
303 * PARAMETERS
304 * proxy The proxy host and port number. The syntax is
305 * "[http://]host[:port][/]". For example,
306 * "www-proxy.my-company.com:80".
307 * no_proxy_domains The list of no-proxy domains or hosts. The syntax is
308 * a list of host or domains, with optional port numbers
309 * separated by a comma, a semi-colon, or a space.
310 * Example: "corp.my-company.com, eng.my-company.com:80"
311 * RETURN
312 * None
313 * EXCEPTIONS
314 * miscellaneous runtime exceptions.
315 * NOTES
319 * by this procedure overrides the initial settings.
316 * When a database session starts, it will assume the proxy settings
317 * in the environment variables "http_proxy" and "no_proxy" if they are
318 * set when the database server instance is started. Proxy settings set
320 *
321 * The general format would be
322 * [http://][<user>[:<password>]@]<host>[:<port>].
323 * Suppose the proxy parameter has username and password, then
324 * begin_request will do the authentication also on the proxy.
325 */
326 PROCEDURE set_proxy(proxy IN VARCHAR2,
327 no_proxy_domains IN VARCHAR2 DEFAULT NULL);
328 PRAGMA restrict_references(set_proxy, wnds, rnds, trust);
329
330 /**
331 * Retrieves the current proxy settings
332 *
333 * PARAMETERS
334 * proxy The proxy host and port number.
335 * no_proxy_domains The list of no-proxy domains or hosts.
336 * RETURN
337 * None
338 * EXCEPTIONS
339 * miscellaneous runtime exceptions.
340 * NOTES
341 * None.
342 */
343 PROCEDURE get_proxy(proxy OUT NOCOPY VARCHAR2,
344 no_proxy_domains OUT NOCOPY VARCHAR2);
345 PRAGMA restrict_references(get_proxy, wnds, rnds, trust);
346
347 /**
348 * Sets whether future HTTP requests should support the HTTP cookies or not,
349 * and the maximum numbers of cookies to be maintained in the current
350 * database user session.
351 *
352 * If the cookie support is enabled for a HTTP request, all cookies that
353 * are saved in the current session and are applicable to the request will
354 * be returned to the Web server in the request in accordance to the HTTP
355 * cookies specification RFC 2109 and to the draft proposal by Netscape
356 * Communications Corporation. Cookies that are set in the response to
357 * the request will be saved in the current session for return to the Web
358 * server in the subsequent requests if the cookie support is enabled
359 * for those requests. If the cookie support is disabled for a HTTP request,
360 * no cookies will be returned to the Web server in the request and the
361 * cookies set in the response to the request will not be saved in the
362 * current session, although the "Set-Cookie" HTTP headers can still be
363 * retrieved from the response.
364 *
365 * The cookie support is enabled for all HTTP requests by default in a
366 * database user session. The default maximum numbers of cookies saved in
367 * the current session totally and per-site are 300 and 20 respectively.
368 * Use this procedure to change the default settings. The default setting
369 * of the cookie support (enabled vs. disabled) affects only the future
370 * requests and has no effect on the existing ones.
371 *
372 * Once a request is created, the cookie support setting may be changed
373 * by using the other set_cookie_support procedure that operates
374 * on a request.
375 *
376 * PARAMETERS
377 * enable Sets whether future HTTP requests should support HTTP
378 * cookies or not. TRUE to enable the support, FALSE to
379 * disable it.
380 * max_cookies Sets the maximum total number of cookies that will be
381 * maintained in the current session.
382 * max_cookies_per_site Sets the maximum number of cookies per each Web
383 * site that will be maintained in the current
384 * session.
385 * EXCEPTIONS
386 * miscellaneous runtime exceptions.
387 * NOTES
388 * If the maximum total number of cookies and the maximum number of cookies
389 * per each Web site are lowered when this procedure is called, the
390 * oldest cookies will be purged first to reduce the number of cookies
391 * to satisfy those new maximum limits.
392 *
393 * Note that the HTTP cookies saved in the current session will last for
394 * the duration of the database session only and there is no persistent
395 * storage for the cookies. An example is given in the package
396 * documentation to illustrate how to use get_cookies and add_cookies
397 * to retrieve, save, and restore the cookies.
398 *
399 * Note that setting the default setting of the cookie support to disabled
400 * with this procedure does not cause the cookies saved in the current
401 * session to be cleared.
402 */
403 PROCEDURE set_cookie_support(enable IN BOOLEAN,
404 max_cookies IN PLS_INTEGER DEFAULT 300,
405 max_cookies_per_site IN PLS_INTEGER DEFAULT 20);
406 PRAGMA restrict_references(set_cookie_support, wnds, rnds, trust);
407
408 /**
409 * Retrieves the current cookie support settings.
410 *
411 * PARAMETERS
412 * enable Whether all future HTTP requests will support the HTTP
413 * cookies or not?
414 * max_cookies The maximum total number of cookies that will be
415 * maintained in the current session.
416 * max_cookies_per_site The maximum number of cookies per each Web site
417 * that will be maintained in the current session.
418 * EXCEPTIONS
419 * miscellaneous runtime exceptions.
420 * NOTES
421 * None.
422 */
423 PROCEDURE get_cookie_support(enable OUT BOOLEAN,
427
424 max_cookies OUT PLS_INTEGER,
425 max_cookies_per_site OUT PLS_INTEGER);
426 PRAGMA restrict_references(get_cookie_support, wnds, rnds, trust);
428 /**
429 * Sets the maximum number of times the UTL_HTTP package should follow HTTP
430 * redirect instruction in the HTTP responses to all future HTTP requests
431 * in the function get_response.
432 *
433 * If max_redirects is set to a positive number, get_response will
434 * automatically follow the redirected URL for the HTTP response status code
435 * 301, 302, and 307 for the HTTP HEAD and GET methods, and 303 for all HTTP
436 * methods, and retry the HTTP request (the request method will be changed
437 * to HTTP GET for the status code 303) at the new location. It keeps
438 * following the redirection until the final, non-redirect location is
439 * reached, or an error occurs, or the maximum number of redirections has
440 * been reached (to prevent an infinite loop). The url and method fields in
441 * the req record will be updated to the last redirected URL and the method
442 * used to access the URL. Set the maximum number of redirects to zero to
443 * disable automatic redirection.
444 *
445 * The maximum number of redirection is 3 by default in a database user
446 * session. Use this procedure to change the default settings. The default
447 * value affects only the future requests and has no effect on the
448 * existing ones.
449 *
450 * Once a request is created, the maximum number of redirection may be
451 * changed by using the other set_follow_redirect procedure that operates
452 * on a request.
453 *
454 * PARAMETERS
455 * max_redirects The maximum number of redirections. Set to zero to
456 * disable redirection.
457 *
458 * EXCEPTIONS
459 * miscellaneous runtime exceptions.
460 * NOTES
461 * None.
462 */
463 PROCEDURE set_follow_redirect(max_redirects IN PLS_INTEGER DEFAULT 3);
464 PRAGMA restrict_references(set_follow_redirect, wnds, rnds, trust);
465
466 /**
467 * Retrieves the follow-redirect setting in the current session.
468 *
469 * PARAMETERS
470 * max_redirects The maximum number of redirection for all future HTTP
471 * requests.
472 *
473 * EXCEPTIONS
474 * miscellaneous runtime exceptions.
475 * NOTES
476 * None.
477 */
478 PROCEDURE get_follow_redirect(max_redirects OUT PLS_INTEGER);
479 PRAGMA restrict_references(get_follow_redirect, wnds, rnds, trust);
480
481 /**
482 * Sets the default character set of the body of all future HTTP requests
483 * when the media type is "text" but the character set is not specified in
484 * the "Content-Type" header. Per the HTTP protocol standard specification,
485 * if the media type of a request or a response is "text" but the character
486 * set information is missing in the "Content-Type" header, the character
487 * set of the request or response body should default to "ISO-8859-1".
488 * Sets the default character set to override the default character set
489 * "ISO-8859-1". Note that a response created for a request inherits the
490 * default body character set of the request instead of that of the current
491 * session.
492 *
493 * The default body character set is "ISO-8859-1" in a database user session.
494 * Use this procedure to change the default settings. The default body
495 * character set setting affects only the future requests and has not
496 * effect on the existing ones.
497 *
498 * Once a request is created, the body character set may be changed by
499 * using the other set_body_charset procedure that operates on a request.
500 *
501 * PARAMETERS
502 * charset The default character set of the request body.
503 * The character set can be in Oracle or Internet Assigned
504 * Numbers Authority (IANA) naming convention. If charset is
505 * NULL, the database character set is assumed.
506 * EXCEPTIONS
507 * miscellaneous runtime exceptions.
508 * NOTES
509 * None.
510 */
511 PROCEDURE set_body_charset(charset IN VARCHAR2 DEFAULT NULL);
512 PRAGMA restrict_references(set_body_charset, wnds, rnds, trust);
513
514 /**
515 * Retrieves the default character set of the body of all future HTTP
516 * requests.
517 *
518 * PARAMETERS
519 * charset The default character set of the body of all future HTTP
520 * requests.
521 *
522 * EXCEPTIONS
523 * miscellaneous runtime exceptions.
524 * NOTES
525 * None.
526 */
527 PROCEDURE get_body_charset(charset OUT NOCOPY VARCHAR2);
528 PRAGMA restrict_references(get_body_charset, wnds, rnds, trust);
529
530 /* The following function, which returns the same default body character set
531 * as the procedure "get_body_charset" does, is for use by the UTL_URL
532 * package only. It is not intended to be used by Oracle users as a public
533 * API.
534 */
535 FUNCTION get_body_charset RETURN VARCHAR2;
536 PRAGMA restrict_references(get_body_charset, wnds, rnds, trust);
537
538 /**
539 * Sets whether future HTTP requests should support the HTTP 1.1 persistent-
540 * connection or not, and the maximum numbers of persistent connections
541 * to be maintained in the current database user session.
542 *
543 * If the persistent-connection support is enabled for a HTTP request,
547 * protocol specification. With the persistent connection support,
544 * the package will keep the network connections to a Web server or the
545 * proxy server open in the package after the request is completed properly
546 * for a subsequent request to the same server to reuse per HTTP 1.1
548 * subsequent HTTP requests may be completed faster because the network
549 * connection latency is avoided. If the persistent-connection support
550 * is disabled for a request, the package will always send the HTTP header
551 * "Connection: close" automatically in the HTTP request and close the
552 * network connection when the request is completed. This setting has no
553 * effect on HTTP requests that follows HTTP 1.0 protocol, for which the
554 * network connections will always be closed after the requests are
555 * completed.
556 *
557 * When a request is being made, the package always attempts to reuse an
558 * existing persistent connection to the target Web server (or proxy server)
559 * if one is available. If none is available, a new network connection will
560 * be initiated. The persistent-connection support setting for a request
561 * affects only whether the network connection should be closed after a
562 * request completes.
563 *
564 * The persistent-connection support is disabled for all HTTP requests by
565 * default in a database user session. The default maximum numbers of
566 * persistent connections saved in the current session is zero. Use this
567 * procedure to change the default settings. The default setting
568 * of the persistent-connection support (enabled vs. disabled) affects only
569 * the future requests and has no effect on the existing ones.
570 *
571 * Once a request is created, the persistent-connection support setting
572 * may be changed by using the other set_persistent_conn_support procedure
573 * that operates on a request.
574 *
575 * Users should note that while the use of persistent connections in UTL_HTTP
576 * may reduce the time it takes to fetch multiple Web pages from the same
577 * server, it consumes precious system resources (network connections) in
578 * the database server. Excessive use of persistent connections may
579 * reduce the scalability of the database server when too many network
580 * connections are kept open in the database server. Therefore, users should
581 * exert discretion when using persistent connection. Network connections
582 * should be kept open only if they will be used immediately by subsequent
583 * requests and should be closed immediately when they are no longer needed.
584 * Also, users are advised to set the default persistent connection support
585 * support as disabled in the session, and to enable persistent connection in
586 * individual HTTP requests as shown in the following code example:
587 *
588 * DECLARE
589 * TYPE vc2_table IS TABLE OF VARCHAR2(256) INDEX BY binary_integer;
590 * paths vc2_table;
591 *
592 * PROCEDURE fetch_pages(paths IN vc2_table) AS
593 * url_prefix VARCHAR2(256) := 'http://www.my-company.com/';
594 * req utl_http.req;
595 * resp utl_http.resp;
596 * data VARCHAR2(1024);
597 * BEGIN
598 * FOR i IN 1..paths.count LOOP
599 * req := utl_http.begin_request(url_prefix || paths(i));
600 *
601 * -- Use persistent connection except for the last request
602 * IF (i < paths.count) THEN
603 * utl_http.set_persistent_conn_support(req, TRUE);
604 * END IF;
605 *
606 * resp := utl_http.get_response(req);
607 *
608 * BEGIN
609 * LOOP
610 * utl_http.read_text(resp, data);
611 * -- do something with the data
612 * END LOOP;
613 * EXCEPTION
614 * WHEN utl_http.end_of_body THEN
615 * NULL;
616 * END;
617 * utl_http.end_response(resp);
618 * END LOOP;
619 * END;
620 *
621 * BEGIN
622 * utl_http.set_persistent_conn_support(FALSE, 1);
623 * paths(1) := '...';
624 * paths(2) := '...';
625 * ...
626 * fetch_pages(paths);
627 * END;
628 *
629 * PARAMETERS
630 * enable Set enable to TRUE to enable persistent connection support.
631 * FALSE otherwise.
632 * max_conns Sets the maximum number of persistent connections that will
633 * be maintained in the current session.
634 *
635 * EXCEPTIONS
636 * miscellaneous runtime exceptions.
637 * NOTES
638 * The default value of the maximum number of persistent connections
639 * in a database session is zero. To truly enable persistent connections,
640 * the user must also set the maximum number of persistent connections to
641 * a positive value or no connections will be kept persistent.
642 */
643 PROCEDURE set_persistent_conn_support(enable IN BOOLEAN,
644 max_conns IN PLS_INTEGER DEFAULT 0);
645 PRAGMA restrict_references(set_persistent_conn_support, wnds, rnds, trust);
646
647 /**
648 * Checks if the persistent connection support is enabled or not, and
649 * retrieves the maximum number of persistent connections maintained
650 * in the current session.
651 *
652 * PARAMETERS
653 * enable TRUE if persistent connection support is enabled.
654 * FALSE otherwise.
655 * max_conns The maximum number of persistent connections that will be
659 * miscellaneous runtime exceptions.
656 * maintained in the current session.
657 *
658 * EXCEPTIONS
660 * NOTES
661 * None.
662 */
663 PROCEDURE get_persistent_conn_support(enable OUT BOOLEAN,
664 max_conns OUT PLS_INTEGER);
665 PRAGMA restrict_references(get_persistent_conn_support, wnds, rnds, trust);
666
667 /**
668 * Sets whether get_response should raise an exception when the Web server
669 * returns a status code that indicates an error (namely, a status code in
670 * the 4xx or 5xx ranges). For example, when the requested URL is not found
671 * in the destination Web server, a 404 (document not found) response status
672 * code is returned. In general, a 4xx or 5xx response is considered an
673 * error response. If response error check is set, get_response will raise
674 * the HTTP_CLIENT_ERROR or HTTP_SERVER_ERROR exception if the status code
675 * indicates an error. Otherwise, get_response will not raise the exception
676 * if the status codes indicates an error. Response error check is turned off
677 * by default.
678 *
679 * PARAMETERS
680 * enable Set to TRUE to check for response error. FALSE otherwise.
681 *
682 * EXCEPTIONS
683 * miscellaneous runtime exceptions.
684 * NOTES
685 * None.
686 */
687 PROCEDURE set_response_error_check(enable IN BOOLEAN DEFAULT FALSE);
688 PRAGMA restrict_references(set_response_error_check, wnds, rnds, trust);
689
690 /**
691 * Checks if response error check is set or not.
692 *
693 * PARAMETERS
694 * enable TRUE if response error check is set. FALSE otherwise.
695 *
696 * EXCEPTIONS
697 * miscellaneous runtime exceptions.
698 * NOTES
699 * None.
700 */
701 PROCEDURE get_response_error_check(enable OUT BOOLEAN);
702 PRAGMA restrict_references(get_response_error_check, wnds, rnds, trust);
703
704 /**
705 * Sets the UTL_HTTP package to raise a detailed exception. By default,
706 * the UTL_HTTP package raises the exception request_failed when a HTTP
707 * request fails. The user may use get_detailed_sqlcode and
708 * get_detailed_sqlerrm to obtained the more detailed information of the
709 * actual error. Use set_detailed_excp_support to ask the UTL_HTTP package
710 * to raise a detailed exception directly instead.
711 *
712 * PARAMETERS
713 * enable Sets to TRUE to ask the UTL_HTTP package to raise a detailed
714 * exception directly. FALSE otherwise.
715 *
716 * EXCEPTIONS
717 * miscellaneous runtime exceptions.
718 * NOTES
719 * None.
720 */
721 PROCEDURE set_detailed_excp_support(enable IN BOOLEAN DEFAULT FALSE);
722 PRAGMA restrict_references(set_detailed_excp_support, wnds, rnds, trust);
723
724 /**
725 * Checks if the UTL_HTTP package will raise a detailed exception or not.
726 *
727 * PARAMETERS
728 * enable TRUE if the UTL_HTTP package will raise a detailed exception.
729 * FALSE otherwise.
730 *
731 * EXCEPTIONS
732 * miscellaneous runtime exceptions.
733 * NOTES
734 * None.
735 */
736 PROCEDURE get_detailed_excp_support(enable OUT BOOLEAN);
737 PRAGMA restrict_references(get_detailed_excp_support, wnds, rnds, trust);
738
739 /**
740 * Sets the Oracle wallet to be used for all HTTP requests over Secured
741 * Socket Layer (SSL), namely HTTPS. When the UTL_HTTP package communicates
742 * with a HTTP server over SSL, the HTTP server presents its digital
743 * certificate, which is signed by a certificate authority, to the UTL_HTTP
744 * package for identification purpose. The Oracle wallet contains the list
745 * of certificate authorities which are trusted by the user of the UTL_HTTP
746 * package. An Oracle wallet is required in order to make a HTTPS request
747 * successfully.
748 *
749 * PARAMETERS
750 * path The directory path that contains the Oracle wallet.
751 * The format is "file:<directory-path>".
752 * password The password needed to open the wallet. There may a second
753 * copy of a wallet in a wallet directory that may be opened
754 * without a password. That second copy of the wallet is for
755 * read only. If password is NULL, the UTL_HTTP package will
756 * open the second, read-only copy of the wallet instead.
757 * See the documentation on Oracle wallets for details.
758 * EXCEPTIONS
759 * miscellaneous runtime exceptions.
760 * NOTES
761 * None.
762 */
763 PROCEDURE set_wallet(path IN VARCHAR2,
764 password IN VARCHAR2 DEFAULT NULL);
765 PRAGMA restrict_references(set_wallet, wnds, rnds, trust);
766
767 /**
768 * Sets the default time-out value for all future HTTP requests that the
769 * UTL_HTTP package should attempt reading the HTTP response from the
770 * Web server or proxy server. This time-out value may be used to avoid the
771 * PL/SQL programs from being blocked by busy Web servers or heavy network
772 * traffic while retrieving Web pages from the Web servers. The default
773 * value of the time-out is 60 seconds.
774 *
775 * PARAMETERS
776 * timeout The network transfer time-out value (in seconds).
777 *
778 * EXCEPTIONS
779 * miscellaneous runtime exceptions.
780 * NOTES
781 * None.
785
782 */
783 PROCEDURE set_transfer_timeout(timeout IN PLS_INTEGER DEFAULT 60);
784 PRAGMA restrict_references(set_transfer_timeout, wnds, rnds, trust);
786 /**
787 * Retrieves the default time-out value for all future HTTP requests.
788 *
789 * PARAMETERS
790 * timeout The network transfer time-out value (in seconds).
791 *
792 * EXCEPTIONS
793 * miscellaneous runtime exceptions.
794 * NOTES
795 * None.
796 */
797 PROCEDURE get_transfer_timeout(timeout OUT PLS_INTEGER);
798 PRAGMA restrict_references(get_transfer_timeout, wnds, rnds, trust);
799
800 /**
801 * Creates a request context. A request context is a context that holds
802 * a wallet and a cookie for private use in making a HTTP request.
803 * This allows the HTTP request to use a wallet and a cookie table
804 * that will not be shared with other applications making HTTP requests
805 * in the same database session.
806 *
807 * PARAMETERS
808 * wallet_path The directory path that contains the Oracle wallet.
809 * The format is "file:<directory-path>".
810 * wallet_password The password needed to open the wallet. There may a
811 * second copy of a wallet in a wallet directory that may be
812 * opened without a password. That second copy of the wallet is
813 * for read only. If password is NULL, the UTL_HTTP package will
814 * open the second, read-only copy of the wallet instead.
815 * See the documentation on Oracle wallets for details.
816 * enable_cookies Sets whether HTTP requests using this request context
817 * should support HTTP cookies or not. TRUE to enable the
818 * support, FALSE to disable it.
819 * max_cookies Sets the maximum total number of cookies that will be
820 * maintained in this request context.
821 * max_cookies_per_site Sets the maximum number of cookies per each Web
822 * site that will be maintained in this request context.
823 *
824 * EXCEPTIONS
825 * miscellaneous runtime exceptions.
826 * NOTES
827 * None.
828 */
829 FUNCTION create_request_context(
830 wallet_path IN VARCHAR2 DEFAULT NULL,
831 wallet_password IN VARCHAR2 DEFAULT NULL,
832 enable_cookies IN BOOLEAN DEFAULT TRUE,
833 max_cookies IN PLS_INTEGER DEFAULT 300,
834 max_cookies_per_site IN PLS_INTEGER DEFAULT 20)
835 RETURN request_context_key;
836 PRAGMA restrict_references(create_request_context, wnds, rnds, trust);
837
838 /**
839 * Destroys a request context. A request cannot be destroyed when it is
840 * in use by a HTTP request or response.
841 *
842 * PARAMETERS
843 * request_context The request context to destroy
844 *
845 * EXCEPTIONS
846 * miscellaneous runtime exceptions.
847 * NOTES
848 * None.
849 */
850 PROCEDURE destroy_request_context(request_context IN OUT request_context_key);
851 PRAGMA restrict_references(destroy_request_context, wnds, rnds, trust);
852
853 /*-------------------------- Request API ------------------------------*/
854 /* The following set of API begin a HTTP request, manipulate its
855 * attributes, and send the request information to the Web server.
856 * When a request is created, it inherits the default settings of the HTTP
857 * cookie support, follow-redirect, body character set, persistent-connection
858 * support, and transfer time-out of the current session. Those settings
859 * may be changed by calling the request API.
860 */
861
862 /**
863 * Begins a new HTTP request. When the function returns, the UTL_HTTP
864 * package has established the network connection to the target Web server,
865 * or the proxy server if a proxy server is to be used, and has sent the
866 * HTTP request line. The PL/SQL program should continue the request by
867 * calling some other API to complete the request.
868 *
869 * PARAMETERS
870 * url The URL of the HTTP request.
871 * method The method to be performed on the resource identified by
872 * the URL.
873 * http_version The HTTP protocol version to use to send the request.
874 * The format of the protocol version is
875 * "HTTP/major-version.minor-version", where major-version
876 * and minor-version are positive number. If this parameter
877 * is set to NULL, the UTL_HTTP package will use the latest
878 * HTTP protocol version that it supports to send the
879 * request. The latest version that the package supports is
880 * 1.1 and it may be upgraded to a later version when one
881 * becomes available. The parameter is set to NULL by
882 * default.
883 * request_context The request context that holds the private wallet and
884 * the cookie table to use in this HTTP request. If this
885 * parameter is NULL, the wallet and cookie table shared in
886 * the current database session will be used instead.
887 *
888 * EXCEPTIONS
889 *
890 * When detailed-exception is disabled:
891 * request_failed the request fails to execute
892 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
893 * get the detailed error message)
897 * bad_argument when some of the arguments passed are not valid.
894 *
895 * When detailed-exception is enabled:
896 *
898 * bad_url when the URL is not valid.
899 * unknown_scheme when the request scheme is not known.
900 * too_many_requests when there are too many open requests.
901 * http_client_error when the HTTP proxy returns 4xx response for a HTTPS
902 * request via the proxy
903 * http_server_error when the HTTP proxy returns 5xx response for a HTTPS
904 * request via the proxy
905 * - plus miscellaneous network and runtime exceptions.
906 * NOTES
907 * The URL passed as an argument to this function will not be examined
908 * for illegal characters per the URL specification RFC 2396, like spaces
909 * for example. The caller should escape those characters with the UTL_URL
910 * package. See the comments of the package for the list of legal
911 * characters in URLs. Note that URLs should consist of US-ASCII
912 * characters only. The use of non-US-ASCII characters in an URL is
913 * generally unsafe.
914 *
915 * URL may contain username and password to authenticate the request to the
916 * server. The general format would be
917 * <scheme>://[<user>[:<password>]@]<host>[:<port>]/[...].
918 * An Oracle wallet must be set before accessing Web servers over the HTTPS
919 * protocol. See the set_wallet procedure on how to set up an Oracle wallet.
920 * To connect to the remote Web server directly, or indirectly through
921 * a HTTP proxy, the UTL_HTTP must have the "connect" ACL privilege to the
922 * remote Web server host or the proxy host respectively.
923 * To use the client-certificate credentials in a wallet to authenticate
924 * with the remote Web server over SSL, the UTL_HTTP must have the
925 * "use-client-certificates" privilege on the wallet.
926 */
927 FUNCTION begin_request(url IN VARCHAR2,
928 method IN VARCHAR2 DEFAULT 'GET',
929 http_version IN VARCHAR2 DEFAULT NULL,
930 request_context IN request_context_key DEFAULT NULL)
931 RETURN req;
932 PRAGMA restrict_references(begin_request, wnds, rnds, trust);
933
934 /**
935 * Sets a HTTP request property.
936 *
937 * PARAMETERS
938 * r The HTTP request
939 * name The name of the HTTP request property. The property name
940 * is case-sensitive.
941 * value The value of the HTTP request property
942 *
943 * EXCEPTIONS
944 *
945 * When detailed-exception is disabled:
946 * request_failed the request fails to execute
947 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
948 * get the detailed error message)
949 *
950 * When detailed-exception is enabled:
951 * bad_argument when some of the arguments passed are not valid.
952 * - plus miscellaneous network and runtime exceptions.
953 */
954 PROCEDURE set_property(r IN OUT NOCOPY req,
955 name IN VARCHAR2,
956 value IN VARCHAR2 DEFAULT NULL);
957 PRAGMA restrict_references(set_property, wnds, rnds, trust);
958
959 /**
960 * Sets a HTTP request header. The request header is sent to the Web server
961 * as soon as it is set.
962 *
963 * PARAMETERS
964 * r The HTTP request
965 * name The name of the HTTP request header
966 * value The value of the HTTP request header
967 *
968 * EXCEPTIONS
969 *
970 * When detailed-exception is disabled:
971 * request_failed the request fails to execute
972 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
973 * get the detailed error message)
974 *
975 * When detailed-exception is enabled:
976 * bad_argument when some of the arguments passed are not valid.
977 * illegal_call when the request body is already sent
978 * - plus miscellaneous network and runtime exceptions.
979 * NOTES
980 * Note that multiple HTTP headers with the same name are allowed per
981 * the HTTP protocol standard. Therefore, setting a header does not
982 * replace a prior header with the same name.
983 * If the request is made using HTTP 1.1 protocol, the UTL_HTTP package
984 * sets the "Host" header automatically for the user.
985 * When the user sets the "Content-Type" header with this procedure,
986 * the UTL_HTTP package looks for the character set information in the
987 * header value. If the character set information is present, it is set as
988 * the character set of the request body. It can be overridden later by
989 * using the set_body_charset procedure.
990 * When the user sets the "Transfer-Encoding" header with the value
991 * "chunked", the UTL_HTTP automatically encodes the request body written
992 * by the write_text, write_line, and write_raw procedures.
993 */
994 PROCEDURE set_header(r IN OUT NOCOPY req,
995 name IN VARCHAR2,
996 value IN VARCHAR2 DEFAULT NULL);
997 PRAGMA restrict_references(set_header, wnds, rnds, trust);
998
999 /**
1000 * Sets the HTTP authentication information in the HTTP request header
1001 * needed for the request to be authorized by the Web server.
1002 *
1003 * PARAMETERS
1007 * scheme The HTTP authentication scheme. Either 'Basic' for
1004 * r The HTTP request
1005 * username The username for the HTTP authentication
1006 * password The password for the HTTP authentication
1008 * the HTTP basic, 'Digest' for the HTTP digest, or
1009 * 'AWS' for Amazon S3 authentication scheme.
1010 * Default is 'Basic'.
1011 * for_proxy Is the HTTP authentication information for the access to
1012 * the HTTP proxy server instead of the Web server? Default
1013 * is FALSE.
1014 *
1015 * EXCEPTIONS
1016 *
1017 * When detailed-exception is disabled:
1018 * request_failed the request fails to execute
1019 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1020 * get the detailed error message)
1021 *
1022 * When detailed-exception is enabled:
1023 * bad_argument when some of the arguments passed are not valid.
1024 * illegal_call when the request body is already sent
1025 * - plus miscellaneous network and runtime exceptions.
1026 * NOTES
1027 * The supported authentication schemes are HTTP basic, digest and
1028 * Amazon S3 authentication schemes.
1029 * For HTTP digest authentication, only "auth" but not "auth-int"
1030 * quality-of protection (qop) is supported.
1031 * For Amazon S3 authentication:
1032 * - All headers used to compute the authentication header - Content-MD5,
1033 * Content-Type, Date, and all X-Amz-* headers - must be set via the
1034 * set_header procedure before set_authentication is called to compute
1035 * and set the authentication header.
1036 * - When an endpoint other than "s3.amazonaws.com" is used, the user
1037 * should specify the correct endpoint to compute the authentication
1038 * header by setting the request property "aws-endpoint" using the
1039 * set_property procedure first. Alternatively, the user may specify
1040 * the CanonicalizedResource string through the request property
1041 * "aws-canonicalized-resource" irrespective of the endpoint to compute
1042 * the authentication header.
1043 */
1044 PROCEDURE set_authentication(r IN OUT NOCOPY req,
1045 username IN VARCHAR2,
1046 password IN VARCHAR2 DEFAULT NULL,
1047 scheme IN VARCHAR2 DEFAULT 'Basic',
1048 for_proxy IN BOOLEAN DEFAULT FALSE);
1049 PRAGMA restrict_references(set_authentication, wnds, rnds, trust);
1050
1051 /**
1052 * Sets the HTTP authentication information in the HTTP request header
1053 * needed for the request to be authorized by the Web server using the
1054 * username and password credential stored in the Oracle wallet.
1055 *
1056 * PARAMETERS
1057 * r The HTTP request
1058 * alias The alias to identify and retrieve the username and
1059 * password credential stored in the Oracle wallet
1060 * scheme The HTTP authentication scheme. Either 'Basic' for
1061 * the HTTP basic, 'Digest' for the HTTP digest, or
1062 * 'AWS' for Amazon S3 authentication scheme.
1063 * Default is 'Basic'.
1064 * for_proxy Is the HTTP authentication information for the access to
1065 * the HTTP proxy server instead of the Web server? Default
1066 * is FALSE.
1067 *
1068 * EXCEPTIONS
1069 *
1070 * When detailed-exception is disabled:
1071 * request_failed the request fails to execute
1072 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1073 * get the detailed error message)
1074 *
1075 * When detailed-exception is enabled:
1076 * bad_argument when some of the arguments passed are not valid.
1077 * illegal_call when the request body is already sent
1078 * - plus miscellaneous network and runtime exceptions.
1079 * NOTES
1080 * To use the password credentials in a wallet, the UTL_HTTP must have
1081 * the "use-passwords" privilege on the wallet.
1082 * The supported authentication schemes are HTTP basic, digest and
1083 * Amazon S3 authentication schemes.
1084 * For HTTP digest authentication, only "auth" but not "auth-int"
1085 * quality-of protection (qop) is supported.
1086 * For Amazon S3 authentication:
1087 * - All headers used to compute the authentication header - Content-MD5,
1088 * Content-Type, Date, and all X-Amz-* headers - must be set via the
1089 * set_header procedure before set_authentication is called to compute
1090 * and set the authentication header.
1091 * - When an endpoint other than "s3.amazonaws.com" is used, the user
1092 * should specify the correct endpoint to compute the authentication
1093 * header by setting the request property "aws-endpoint" using the
1094 * set_property procedure first. Alternatively, the user may specify
1095 * the CanonicalizedResource string through the request property
1096 * "aws-canonicalized-resource" irrespective of the endpoint to compute
1097 * the authentication header.
1098 */
1099 PROCEDURE set_authentication_from_wallet(r IN OUT NOCOPY req,
1100 alias IN VARCHAR2,
1101 scheme IN VARCHAR2 DEFAULT 'Basic',
1102 for_proxy IN BOOLEAN DEFAULT FALSE);
1103 PRAGMA restrict_references(set_authentication_from_wallet,
1107 * Enables (or disables) the support for the HTTP cookies in this request.
1104 wnds, rnds, trust);
1105
1106 /**
1108 *
1109 * If the cookie support is enabled for a HTTP request, all cookies that
1110 * are saved in the current session and are applicable to the request will
1111 * be returned to the Web server in the request in accordance to the HTTP
1112 * cookies specification RFC 2109 and to the draft proposal by Netscape
1113 * Communications Corporation. Cookies that are set in the response to
1114 * the request will be saved in the current session for return to the Web
1115 * server in the subsequent requests if the cookie support is enabled
1116 * for those requests. If the cookie support is disabled for a HTTP request,
1117 * no cookies will be returned to the Web server in the request and the
1118 * cookies set in the response to the request will not be saved in the
1119 * current session, although the "Set-Cookie" HTTP headers can still be
1120 * retrieved from the response.
1121 *
1122 * Use this procedure to change the cookie support setting a request inherits
1123 * from the session's default setting.
1124 *
1125 * PARAMETERS
1126 * r The HTTP request
1127 * enable Set enable to TRUE to enable the HTTP cookie support.
1128 * FALSE otherwise.
1129 * EXCEPTIONS
1130 * miscellaneous runtime exceptions.
1131 * NOTES
1132 * Note that the HTTP cookies saved in the current session will last for
1133 * the duration of the database session only and there is no persistent
1134 * storage for the cookies. An example is given in the package
1135 * documentation to illustrate how to use get_cookies and add_cookies
1136 * to retrieve, save, and restore the cookies.
1137 */
1138 PROCEDURE set_cookie_support(r IN OUT NOCOPY req,
1139 enable IN BOOLEAN DEFAULT TRUE);
1140 PRAGMA restrict_references(set_cookie_support, wnds, rnds, trust);
1141
1142 /**
1143 * Sets the maximum number of times the UTL_HTTP package should follow HTTP
1144 * redirect instruction in the HTTP response to this request in the
1145 * function get_response.
1146 *
1147 * If max_redirects is set to a positive number, get_response will
1148 * automatically follow the redirected URL for the HTTP response status code
1149 * 301, 302, and 307 for the HTTP HEAD and GET methods, and 303 for all HTTP
1150 * methods, and retry the HTTP request (the request method will be changed
1151 * to HTTP GET for the status code 303) at the new location. It keeps
1152 * following the redirection until the final, non-redirect location is
1153 * reached, or an error occurs, or the maximum number of redirections has
1154 * been reached (to prevent an infinite loop). The url and method fields in
1155 * the req record will be updated to the last redirected URL and the method
1156 * used to access the URL. Set the maximum number of redirects to zero to
1157 * disable automatic redirection.
1158 *
1159 * Use this procedure to change the maximum number of redirections a request
1160 * inherits from the session's default setting.
1161 *
1162 * PARAMETERS
1163 * r The HTTP request
1164 * max_redirects The maximum number of redirections. Set to zero to
1165 * disable redirection.
1166 *
1167 * EXCEPTIONS
1168 *
1169 * When detailed-exception is disabled:
1170 * request_failed the request fails to execute
1171 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1172 * get the detailed error message)
1173 *
1174 * When detailed-exception is enabled:
1175 * bad_argument when some of the arguments passed are not valid.
1176 * - plus miscellaneous runtime exceptions.
1177 * NOTES
1178 * set_follow_redirect must be called before get_response for any
1179 * redirection to take effect.
1180 */
1181 PROCEDURE set_follow_redirect(r IN OUT NOCOPY req,
1182 max_redirects IN PLS_INTEGER DEFAULT 3);
1183 PRAGMA restrict_references(set_follow_redirect, wnds, rnds, trust);
1184
1185 /**
1186 * Sets the character set of the request body when the media type is "text"
1187 * but the character set is not specified in the "Content-Type" header.
1188 * Per the HTTP protocol standard specification, if the media type of a
1189 * request or a response is "text" but the character set information is
1190 * missing in the "Content-Type" header, the character set of the request
1191 * or response body should default to "ISO-8859-1".
1192 *
1193 * Use this procedure to change the default body character set a request
1194 * inherits from the session's default setting.
1195 *
1196 * PARAMETERS
1197 * r The HTTP request
1198 * charset The default character set of the request body.
1199 * The character set can be in Oracle or Internet Assigned
1200 * Numbers Authority (IANA) naming convention. If charset is
1201 * NULL, the database character set is assumed.
1202 *
1203 * EXCEPTIONS
1204 *
1205 * When detailed-exception is disabled:
1206 * request_failed the request fails to execute
1207 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1208 * get the detailed error message)
1209 *
1210 * When detailed-exception is enabled:
1211 * bad_argument when some of the arguments passed are not valid.
1215 */
1212 * - plus miscellaneous network or runtime exceptions.
1213 * NOTES
1214 * None.
1216 PROCEDURE set_body_charset(r IN OUT NOCOPY req,
1217 charset IN VARCHAR2 DEFAULT NULL);
1218 PRAGMA restrict_references(set_body_charset, wnds, rnds, trust);
1219
1220 /**
1221 * Enables (or disables) the support for the HTTP 1.1 persistent-connection
1222 * in this request.
1223 *
1224 * If the persistent-connection support is enabled for a HTTP request,
1225 * the package will keep the network connections to a Web server or the
1226 * proxy server open in the package after the request is completed properly
1227 * for a subsequent request to the same server to reuse per HTTP 1.1
1228 * protocol specification. With the persistent connection support,
1229 * subsequent HTTP requests may be completed faster because the network
1230 * connection latency is avoided. If the persistent-connection support
1231 * is disabled for a request, the package will always send the HTTP header
1232 * "Connection: close" automatically in the HTTP request and close the
1233 * network connection when the request is completed. This setting has no
1234 * effect on HTTP requests that follows HTTP 1.0 protocol, for which the
1235 * network connections will always be closed after the requests are
1236 * completed.
1237 *
1238 * When a request is being made, the package always attempts to reuse an
1239 * existing persistent connection to the target Web server (or proxy server)
1240 * if one is available. If none is available, a new network connection will
1241 * be initiated. The persistent-connection support setting for a request
1242 * affects only whether the network connection should be closed after a
1243 * request completes.
1244 *
1245 * Use this procedure to change the persistent-connection support setting a
1246 * request inherits from the session's default setting.
1247 *
1248 * Users should note that while the use of persistent connections in UTL_HTTP
1249 * may reduce the time it takes to fetch multiple Web pages from the same
1250 * server, it consumes precious system resources (network connections) in
1251 * the database server. Also, excessive use of persistent connections may
1252 * reduce the scalability of the database server when too many network
1253 * connections are kept open in the database server. Therefore, users should
1254 * exert discretion when using persistent connection. Network connections
1255 * should be kept open only if they will be used immediately by subsequent
1256 * requests and should be closed immediately when they are no longer needed.
1257 * Also, users are advised to set the default persistent connection support
1258 * support as disabled in the session, and to enable persistent connection in
1259 * individual HTTP requests as shown in the following code example:
1260 *
1261 * DECLARE
1262 * TYPE vc2_table IS TABLE OF VARCHAR2(256) INDEX BY binary_integer;
1263 * paths vc2_table;
1264 *
1265 * PROCEDURE fetch_pages(paths IN vc2_table) AS
1266 * url_prefix VARCHAR2(256) := 'http://www.my-company.com/';
1267 * req utl_http.req;
1268 * resp utl_http.resp;
1269 * data VARCHAR2(1024);
1270 * BEGIN
1271 * FOR i IN 1..paths.count LOOP
1272 * req := utl_http.begin_request(url_prefix || paths(i));
1273 *
1274 * -- Use persistent connection except for the last request
1275 * IF (i < paths.count) THEN
1276 * utl_http.set_persistent_conn_support(req, pcn);
1277 * END IF;
1278 *
1279 * resp := utl_http.get_response(req);
1280 *
1281 * BEGIN
1282 * LOOP
1283 * utl_http.read_text(resp, data);
1284 * -- do something with the data
1285 * END LOOP;
1286 * EXCEPTION
1287 * WHEN utl_http.end_of_body THEN
1288 * NULL;
1289 * END;
1290 * utl_http.end_response(resp);
1291 * END LOOP;
1292 * END;
1293 *
1294 * BEGIN
1295 * utl_http.set_persistent_conn_support(FALSE, 1);
1296 * paths(1) := '...';
1297 * paths(2) := '...';
1298 * ...
1299 * fetch_pages(paths);
1300 * END;
1301 *
1302 * PARAMETERS
1303 * r The HTTP request
1304 * enable TRUE to keep the network connection persistent.
1305 * FALSE otherwise.
1306 *
1307 * EXCEPTIONS
1308 *
1309 * When detailed-exception is disabled:
1310 * request_failed the request fails to execute
1311 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1312 * get the detailed error message)
1313 *
1314 * When detailed-exception is enabled:
1315 * bad_argument when some of the arguments passed are not valid.
1316 * illegal_call when the request body is already sent
1317 * - plus miscellaneous network or runtime exceptions.
1318 * NOTES
1319 * The default value of the maximum number of persistent connections
1320 * in a database session is zero. To truly enable persistent connections,
1321 * the user must also set the maximum number of persistent connections to
1322 * a positive value or no connections will be kept persistent.
1323 */
1324 PROCEDURE set_persistent_conn_support(r IN OUT NOCOPY req,
1325 enable IN BOOLEAN DEFAULT FALSE);
1326 PRAGMA restrict_references(set_persistent_conn_support, wnds, rnds, trust);
1330 * the HTTP response of this HTTP request from the Web server or proxy
1327
1328 /**
1329 * Sets the time-out value that the UTL_HTTP package should attempt reading
1331 * server. This time-out value may be used to avoid the PL/SQL programs
1332 * from being blocked by busy Web servers or heavy network traffic while
1333 * retrieving Web pages from the Web servers. The default value of the
1334 * time-out is 60 seconds.
1335 *
1336 * PARAMETERS
1337 * r The HTTP request
1338 * timeout The network transfer time-out value (in seconds).
1339 *
1340 * EXCEPTIONS
1341 * miscellaneous runtime exceptions.
1342 * NOTES
1343 * None.
1344 */
1345 PROCEDURE set_transfer_timeout(r IN OUT NOCOPY req,
1346 timeout IN PLS_INTEGER DEFAULT 60);
1347 PRAGMA restrict_references(set_transfer_timeout, wnds, rnds, trust);
1348
1349 /**
1350 * Writes some text data in the HTTP request body. As soon as some data is
1351 * sent as the HTTP request body, the HTTP request headers section is
1352 * completed. Text data is automatically converted from the database
1353 * character set to the request body character set.
1354 *
1355 * PARAMETERS
1356 * r The HTTP request
1357 * data The text data to send in the HTTP request body
1358 *
1359 * EXCEPTIONS
1360 *
1361 * When detailed-exception is disabled:
1362 * request_failed the request fails to execute
1363 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1364 * get the detailed error message)
1365 *
1366 * When detailed-exception is enabled:
1367 * bad_argument when some of the arguments passed are not valid.
1368 * - plus miscellaneous network or runtime exceptions.
1369 * NOTES
1370 * A HTTP client must always let the remote Web server to know the length
1371 * of the request body it is sending. If the amount of data is known
1372 * beforehand, the user can set the "Content-Length" header in the request,
1373 * where the length of the content is measured in bytes instead of
1374 * characters. If the length of the request body is not know beforehand,
1375 * the user can choose to send the request body using the HTTP 1.1 chunked
1376 * transfer-encoding format. The request body will be sent in chunks where
1377 * the length of each chunk is sent before the chunk is sent. The UTL_HTTP
1378 * package performs chunked transfer-encoding on the request body
1379 * transparently when the "Transfer-Encoding: chunked" header is set.
1380 * Note that some HTTP-1.1-based Web servers or CGI programs do not support
1381 * or accept the request body encoding in the HTTP 1.1 chunked
1382 * transfer-encoding format. See the set_header procedure for details.
1383 * If the user sends the "Content-Length" header, the user should note
1384 * that the length specify in the header should be the byte-length of the
1385 * textual request body after it is converted from the database character
1386 * set to the request body character set. When either one of the two
1387 * character sets is a multi-byte character set, the precise byte-length of
1388 * the request body in the request body character set may not be known
1389 * beforehand. In that case, the user may perform the character set
1390 * conversion explicitly, determine the byte-length of the results, send
1391 * the "Content-Length" header, and the results using the write_raw
1392 * procedure to avoid the automatic character set conversion.
1393 * Or if the remove Web server or CGI programs allows, the user may send
1394 * the request body using the HTTP 1.1 chunked transfer-encoding format
1395 * where the UTL_HTTP will handle the length of the chunks transparently.
1396 */
1397 PROCEDURE write_text(r IN OUT NOCOPY req,
1398 data IN VARCHAR2 CHARACTER SET ANY_CS);
1399 PRAGMA restrict_references(write_text, wnds, rnds, trust);
1400
1401 /**
1402 * Writes a text line in the HTTP request body and ends the line with
1403 * new-line characters (CRLF as defined in UTL_TCP). As soon as some data
1404 * is sent as the HTTP request body, the HTTP request headers section is
1405 * completed. Text data is automatically converted from the database
1406 * character set to the request body character set.
1407 *
1408 * PARAMETERS
1409 * r The HTTP request
1410 * data The text line to send in the HTTP request body
1411 *
1412 * EXCEPTIONS
1413 *
1414 * When detailed-exception is disabled:
1415 * request_failed the request fails to execute
1416 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1417 * get the detailed error message)
1418 *
1419 * When detailed-exception is enabled:
1420 * bad_argument when some of the arguments passed are not valid.
1421 * - plus miscellaneous network or runtime exceptions.
1422 * NOTES
1423 * A HTTP client must always let the remote Web server to know the length
1424 * of the request body it is sending. If the amount of data is known
1425 * beforehand, the user can set the "Content-Length" header in the request,
1426 * where the length of the content is measured in bytes instead of
1427 * characters. If the length of the request body is not know beforehand,
1428 * the user can choose to send the request body using the HTTP 1.1 chunked
1429 * transfer-encoding format. The request body will be sent in chunks where
1430 * the length of each chunk is sent before the chunk is sent. The UTL_HTTP
1431 * package performs chunked transfer-encoding on the request body
1435 * transfer-encoding format. See the set_header procedure for details.
1432 * transparently when the "Transfer-Encoding: chunked" header is set.
1433 * Note that some HTTP-1.1-based Web servers or CGI programs do not support
1434 * or accept the request body encoding in the HTTP 1.1 chunked
1436 * If the user sends the "Content-Length" header, the user should note
1437 * that the length specify in the header should be the byte-length of the
1438 * textual request body after it is converted from the database character
1439 * set to the request body character set. When either one of the two
1440 * character sets is a multi-byte character set, the precise byte-length of
1441 * the request body in the request body character set may not be known
1442 * beforehand. In that case, the user may perform the character set
1443 * conversion explicitly, determine the byte-length of the results, send
1444 * the "Content-Length" header, and the results using the write_raw
1445 * procedure to avoid the automatic character set conversion.
1446 * Or if the remove Web server or CGI programs allows, the user may send
1447 * the request body using the HTTP 1.1 chunked transfer-encoding format
1448 * where the UTL_HTTP will handle the length of the chunks transparently.
1449 */
1450 PROCEDURE write_line(r IN OUT NOCOPY req,
1451 data IN VARCHAR2 CHARACTER SET ANY_CS);
1452 PRAGMA restrict_references(write_line, wnds, rnds, trust);
1453
1454 /**
1455 * Writes some binary data in the HTTP request body. As soon as some data is
1456 * sent as the HTTP request body, the HTTP request headers section is
1457 * completed.
1458 *
1459 * PARAMETERS
1460 * r The HTTP request
1461 * data The binary data to send in the HTTP request body
1462 *
1463 * EXCEPTIONS
1464 *
1465 * When detailed-exception is disabled:
1466 * request_failed the request fails to execute
1467 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1468 * get the detailed error message)
1469 *
1470 * When detailed-exception is enabled:
1471 * bad_argument when some of the arguments passed are not valid.
1472 * - plus miscellaneous network or runtime exceptions.
1473 * NOTES
1474 * A HTTP client must always let the remote Web server to know the length
1475 * of the request body it is sending. If the amount of data is known
1476 * beforehand, the user can set the "Content-Length" header in the request,
1477 * where the length of the content is measured in bytes instead of
1478 * characters. If the length of the request body is not know beforehand,
1479 * the user can choose to send the request body using the HTTP 1.1 chunked
1480 * transfer-encoding format. The request body will be sent in chunks where
1481 * the length of each chunk is sent before the chunk is sent. The UTL_HTTP
1482 * package performs chunked transfer-encoding on the request body
1483 * transparently when the "Transfer-Encoding: chunked" header is set.
1484 * Note that some HTTP-1.1-based Web servers or CGI programs do not support
1485 * or accept the request body encoding in the HTTP 1.1 chunked
1486 * transfer-encoding format. See the set_header procedure for details.
1487 */
1488 PROCEDURE write_raw(r IN OUT NOCOPY req,
1489 data IN RAW);
1490 PRAGMA restrict_references(write_raw, wnds, rnds, trust);
1491
1492 /**
1493 * Ends the HTTP request. In the not-so-normal situation when a PL/SQL
1494 * program wants to terminates the HTTP request without completing the
1495 * request and waiting for the response, the program can call this procedure
1496 * to terminate the request. Otherwise, the program should go through the
1497 * normal sequence of beginning a request, getting the response, and
1498 * closing the response. The network connection will always be closed and
1499 * will not be reused.
1500 *
1501 * PARAMETERS
1502 * r The HTTP request
1503 *
1504 * EXCEPTIONS
1505 *
1506 * When detailed-exception is disabled:
1507 * request_failed the request fails to execute
1508 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1509 * get the detailed error message)
1510 *
1511 * When detailed-exception is enabled:
1512 * bad_argument when some of the arguments passed are not valid.
1513 * - plus miscellaneous network or runtime exceptions.
1514 * NOTES
1515 * None.
1516 */
1517 PROCEDURE end_request(r IN OUT NOCOPY req);
1518 PRAGMA restrict_references(end_request, wnds, rnds, trust);
1519
1520 /*-------------------------- Response API ------------------------------*/
1521 /* The following set of API manipulate a HTTP response obtained from
1522 * get_response and to receive the response information from the Web server.
1523 * When a response is created for a request, it inherits settings of the
1524 * HTTP cookie support, follow-redirect, body character set, persistent-
1525 * connection support, and transfer time-out from the request. Only the body
1526 * character set may be changed by calling the response API.
1527 */
1528
1529 /**
1530 * Reads the HTTP response. When this procedure returns, the status line
1531 * and the HTTP response headers have been read and processed. The status
1532 * code, reason phrase and the HTTP protocol version are stored in the
1533 * response record. This function completes the HTTP headers section.
1534 *
1535 * PARAMETERS
1536 * r The HTTP request
1540 * The request will not be ended if a 100 response is
1537 * return_info_response Return 100 informational response or not. TRUE
1538 * means get_response should return 100 informational
1539 * response when it is received from the HTTP server.
1541 * returned. FALSE means the API should ignore any 100
1542 * informational response received from the HTTP server
1543 * and should return the following non-100 response
1544 * instead. The default is FALSE.
1545 * See notes below for details.
1546 *
1547 *
1548 * EXCEPTIONS
1549 *
1550 * When detailed-exception is disabled:
1551 * request_failed the request fails to execute
1552 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1553 * get the detailed error message)
1554 *
1555 * When detailed-exception is enabled:
1556 * bad_argument when some of the arguments passed are not valid.
1557 * When response error check is enabled:
1558 * http_client_error when the response code is in 400 range
1559 * http_server_error when the response code is in 500 range
1560 * - plus miscellaneous network or runtime exceptions.
1561 * NOTES
1562 * - The request will be ended when this functions returns regardless of
1563 * whether an exception is raised or not. There is no need to end
1564 * the request with end_request.
1565 * - If URL redirection occurs, the url and method fields in the req
1566 * record will be updated to the last redirected URL and the method used
1567 * to access the URL.
1568 *
1569 * Notes on 100 Continue:
1570 * In certain situations (initiated by the HTTP client or not), the HTTP
1571 * server may return a 1xx informational response. The user who does not
1572 * expect such a response may indicate to get_response to ignore the response
1573 * and proceed to receive the regular response. In the case when the user
1574 * expects such a response, he can indicate to get_response to return the
1575 * response. For example, when a user is issuing a HTTP POST request with a
1576 * large request body, the user may want to check with the HTTP server to
1577 * ensure that the server will accept the request before sending the data.
1578 * To do so, the user will send the additional "Expect: 100-continue" request
1579 * header, check for "100 Continue" response from the server before
1580 * proceeding to send the request body. Then, the user will get the regular
1581 * HTTP response as he normally does. The following code example illustrates
1582 * this:
1583 * DECLARE
1584 * data VARCHAR2(1024) := '...';
1585 * req utl_http.req;
1586 * resp utl_http.resp;
1587 * BEGIN
1588 *
1589 * req := utl_http.begin_request('http://www.acme.com/receiver', 'POST');
1590 * utl_http.set_header(req, 'Content-Length', length(data));
1591 * -- Ask HTTP server to return "100 Continue" response
1592 * utl_http.set_header(req, 'Expect', '100-continue');
1593 * resp := utl_http.get_response(req, TRUE);
1594 *
1595 * -- Check for and dispose "100 Continue" response
1596 * IF (resp.status_code <> 100) THEN
1597 * utl_http.end_response(resp);
1598 * raise_application_error(20000, 'Request rejected');
1599 * END IF;
1600 * utl_http.end_response(resp);
1601 *
1602 * -- Now, send the request body
1603 * utl_http.write_text(req, data);
1604
1605 * -- Get the regular response
1606 * resp := utl_http.get_response(req);
1607 * utl_http.read_text(resp, data);
1608 *
1609 * utl_http.end_response(resp);
1610 *
1611 * END;
1612 *
1613 */
1614 FUNCTION get_response(r IN OUT NOCOPY req,
1615 return_info_response BOOLEAN DEFAULT FALSE)
1616 RETURN resp;
1617 PRAGMA restrict_references(get_response, wnds, rnds, trust);
1618
1619 /**
1620 * Returns the number of HTTP response headers returned in the response.
1621 *
1622 * PARAMETERS
1623 * r The HTTP response
1624 *
1625 * EXCEPTIONS
1626 *
1627 * When detailed-exception is disabled:
1628 * request_failed the request fails to execute
1629 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1630 * get the detailed error message)
1631 *
1632 * When detailed-exception is enabled:
1633 * bad_argument when some of the arguments passed are not valid.
1634 * - plus miscellaneous network or runtime exceptions.
1635 * NOTES
1636 * If the response body returned by the remote Web server is encoded
1637 * in chunked transfer encoding format, the trailer headers that are returned
1638 * at the end of the response body will be added to the response and
1639 * the response header count will be updated. Users can retrieve the
1640 * additional headers after the end of the response body is reached and
1641 * before they end the response.
1642 */
1643 FUNCTION get_header_count(r IN OUT NOCOPY resp) RETURN PLS_INTEGER;
1644 PRAGMA restrict_references(get_header_count, wnds, rnds, trust);
1645
1646 /**
1647 * Returns the n-th HTTP response header name and value returned in the
1648 * response.
1649 *
1650 * PARAMETERS
1651 * r The HTTP response
1652 * n The n-th header to return
1653 * name The name of the HTTP respone header
1657 *
1654 * value The value of the HTTP response header
1655 *
1656 * EXCEPTIONS
1658 * When detailed-exception is disabled:
1659 * request_failed the request fails to execute
1660 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1661 * get the detailed error message)
1662 *
1663 * When detailed-exception is enabled:
1664 * bad_argument when some of the arguments passed are not valid.
1665 * header_not_found when the n-th header is not found.
1666 * - plus miscellaneous runtime exceptions.
1667 * NOTES
1668 * If the response body returned by the remote Web server is encoded
1669 * in chunked transfer encoding format, the trailer headers that are returned
1670 * at the end of the response body will be added to the response and
1671 * the response header count will be updated. Users can retrieve the
1672 * additional headers after the end of the response body is reached and
1673 * before they end the response.
1674 */
1675 PROCEDURE get_header(r IN OUT NOCOPY resp,
1676 n IN PLS_INTEGER,
1677 name OUT NOCOPY VARCHAR2,
1678 value OUT NOCOPY VARCHAR2);
1679 PRAGMA restrict_references(get_header, wnds, rnds, trust);
1680
1681 /**
1682 * Returns the HTTP response header value returned in the response given
1683 * the name of the header.
1684 *
1685 * PARAMETERS
1686 * r The HTTP response
1687 * name The name of the HTTP response header
1688 * value The value of the HTTP response header
1689 * n The nth occurrence of HTTP response header by the specified
1690 * name to return. Default is 1.
1691 *
1692 * EXCEPTIONS
1693 *
1694 * When detailed-exception is disabled:
1695 * request_failed the request fails to execute
1696 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1697 * get the detailed error message)
1698 *
1699 * When detailed-exception is enabled:
1700 * bad_argument when some of the arguments passed are not valid.
1701 * header_not_found when the n-th header is not found.
1702 * - plus miscellaneous runtime exceptions.
1703 * NOTES
1704 * If the response body returned by the remote Web server is encoded
1705 * in chunked transfer encoding format, the trailer headers that are returned
1706 * at the end of the response body will be added to the response and
1707 * the response header count will be updated. Users can retrieve the
1708 * additional headers after the end of the response body is reached and
1709 * before they end the response.
1710 */
1711 PROCEDURE get_header_by_name(r IN OUT NOCOPY resp,
1712 name IN VARCHAR2,
1713 value OUT NOCOPY VARCHAR2,
1714 n IN PLS_INTEGER DEFAULT 1);
1715 PRAGMA restrict_references(get_header_by_name, wnds, rnds, trust);
1716
1717 /**
1718 * Retrieves the HTTP authentication information needed for the request to be
1719 * accepted by the Web server as indicated in the HTTP response header.
1720 *
1721 * PARAMETERS
1722 * r The HTTP response
1723 * scheme The scheme for the required HTTP authentication
1724 * realm The realm for the required HTTP authentication.
1725 * for_proxy Returns the HTTP authentication information required for the
1726 * access to the HTTP proxy server instead of the Web server?
1727 * Default is FALSE.
1728 *
1729 * EXCEPTIONS
1730 *
1731 * When detailed-exception is disabled:
1732 * request_failed the request fails to execute
1733 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1734 * get the detailed error message)
1735 *
1736 * When detailed-exception is enabled:
1737 * bad_argument when some of the arguments passed are not valid.
1738 * - plus miscellaneous runtime exceptions.
1739 * NOTES
1740 * None.
1741 */
1742 PROCEDURE get_authentication(r IN OUT NOCOPY resp,
1743 scheme OUT NOCOPY VARCHAR2,
1744 realm OUT NOCOPY VARCHAR2,
1745 for_proxy IN BOOLEAN DEFAULT FALSE);
1746 PRAGMA restrict_references(get_authentication, wnds, rnds, trust);
1747
1748 /**
1749 * Sets the character set of the response body when the media type is "text"
1750 * but the character set is not specified in the "Content-Type" header.
1751 * Per the HTTP protocol standard specification, if the media type of a
1752 * request or a response is "text" but the character set information is
1753 * missing in the "Content-Type" header, the character set of the request
1754 * or response body should default to "ISO-8859-1".
1755 *
1756 * Use this procedure to change the default body character set a response
1757 * inherits from the request.
1758 *
1759 * PARAMETERS
1760 * r The HTTP response
1761 * charset The default character set of the response body. The character
1762 * set can be in Oracle or Internet Assigned Numbers Authority
1763 * (IANA) naming convention. If charset is NULL, the database
1764 * character set is assumed.
1765 *
1766 * EXCEPTIONS
1767 *
1768 * When detailed-exception is disabled:
1772 *
1769 * request_failed the request fails to execute
1770 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1771 * get the detailed error message)
1773 * When detailed-exception is enabled:
1774 * bad_argument when some of the arguments passed are not valid.
1775 * - plus miscellaneous runtime exceptions.
1776 * NOTES
1777 * None.
1778 */
1779 PROCEDURE set_body_charset(r IN OUT NOCOPY resp,
1780 charset IN VARCHAR2 DEFAULT NULL);
1781 PRAGMA restrict_references(set_body_charset, wnds, rnds, trust);
1782
1783 /**
1784 * Reads the HTTP response body in text form and returns the output in the
1785 * caller-supplied buffer. The end_of_body exception will be raised if the
1786 * end of the HTTP response body is reached. Text data is automatically
1787 * converted from the response body character set to the database character
1788 * set.
1789 *
1790 * PARAMETERS
1791 * r The HTTP response
1792 * data The HTTP response body in text form
1793 * len The maximum number of characters of data to read. If len is
1794 * NULL, this procedure will read as much input as possible to
1795 * fill the buffer allocated in data. The actual amount of data
1796 * returned may be less than that specified if not so much data
1797 * is available before the end of the HTTP response body is
1798 * reached or the transfer_timeout amount of time has elapsed.
1799 * The default is NULL.
1800 *
1801 * EXCEPTIONS
1802 * end_of_body when no data can be returned because the end of
1803 * response body is reached.
1804 *
1805 * When detailed-exception is disabled:
1806 * request_failed the request fails to execute
1807 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1808 * get the detailed error message)
1809 *
1810 * When detailed-exception is enabled:
1811 * bad_argument when some of the arguments passed are not valid.
1812 * transfer_timeout no data is read and a read time-out occurred.
1813 * partial_multibyte_char - no data is read and a partial multi-byte
1814 * character is found at the end of the response body.
1815 * - plus miscellaneous network or runtime exceptions.
1816 * NOTES
1817 * The UTL_HTTP package supports HTTP 1.1 chunked transfer-encoding.
1818 * When the response body is returned in chunked transfer-encoding format
1819 * as indicated in the response header, the package automatically decodes
1820 * the chunks and return the response body in "dechunked" format.
1821 * If transfer time-out is set in the request of this response, this
1822 * procedure will wait for each data packet to be ready to read until
1823 * time-out occurs. If it occurs, this procedure will stop reading and
1824 * return all the data read successfully. If no data is read successfully,
1825 * the transfer_timeout exception will be raised. The exception can be
1826 * handled and the read operation can be retried at a later time.
1827 * If a partial multi-byte character is found at the end of response body,
1828 * this function will stop reading and return all the complete multi-byte
1829 * characters read successfully. If no complete character is read
1830 * successfully, the partial_multibyte_char exception will be raised.
1831 * The exception can be handled and the bytes of that partial multi-byte
1832 * character can be read as binary by the read_raw procedure. If a partial
1833 * multi-byte character is seen in the middle of the response body because
1834 * the remaining bytes of the character have not arrived and read time-out
1835 * occurs, the transfer_timeout exception will be raised instead.
1836 * The exception can be handled and the read operation can be retried
1837 * at a later time.
1838 * When the "Content-Type" response header specifies the character set
1839 * of the response body and the character set is unknown to or unsupported by
1840 * Oracle, the "ORA-01482: unsupported character set" exception will be
1841 * raised if the user tries to read the response body as text. The user
1842 * may either read the response body as binary using the read_raw procedure,
1843 * or set the character set of the response body explicitly using the
1844 * set_body_charset procedure and read the response body as text again.
1845 */
1846 PROCEDURE read_text(r IN OUT NOCOPY resp,
1847 data OUT NOCOPY VARCHAR2 CHARACTER SET ANY_CS,
1848 len IN PLS_INTEGER DEFAULT NULL);
1849 PRAGMA restrict_references(read_text, wnds, rnds, trust);
1850
1851 /**
1852 * Reads the HTTP response body in text form until the end of line is
1853 * reached and returns the output in the caller-supplied buffer. The end of
1854 * line is as defined in the function read_line of UTL_TCP. The end_of_body
1855 * exception will be raised if the end of the HTTP response body is reached.
1856 * Text data is automatically converted from the response body character set
1857 * to the database character set.
1858 *
1859 * PARAMETERS
1860 * r The HTTP response
1861 * data The HTTP response body in text form
1862 * remove_crlf Remove the newline characters?
1863 *
1864 * EXCEPTIONS
1865 * end_of_body when no data can be returned because the end of
1866 * response body is reached.
1867 *
1868 * When detailed-exception is disabled:
1872 *
1869 * request_failed the request fails to execute
1870 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1871 * get the detailed error message)
1873 * When detailed-exception is enabled:
1874 * bad_argument when some of the arguments passed are not valid.
1875 * transfer_timeout no data is read and a read time-out occurred.
1876 * partial_multibyte_char - no data is read and a partial multi-byte
1877 * character is found at the end of the response body.
1878 * - plus miscellaneous network or runtime exceptions.
1879 * NOTES
1880 * The UTL_HTTP package supports HTTP 1.1 chunked transfer-encoding.
1881 * When the response body is returned in chunked transfer-encoding format
1882 * as indicated in the response header, the package automatically decodes
1883 * the chunks and return the response body in "dechunked" format.
1884 * If transfer time-out is set in the request of this response, this
1885 * procedure will wait for each data packet to be ready to read until
1886 * time-out occurs. If it occurs, this procedure will stop reading and
1887 * return all the data read successfully. If no data is read successfully,
1888 * the transfer_timeout exception will be raised. The exception can be
1889 * handled and the read operation can be retried at a later time.
1890 * If a partial multi-byte character is found at the end of response body,
1891 * this function will stop reading and return all the complete multi-byte
1892 * characters read successfully. If no complete character is read
1893 * successfully, the partial_multibyte_char exception will be raised.
1894 * The exception can be handled and the bytes of that partial multi-byte
1895 * character can be read as binary by the read_raw procedure. If a partial
1896 * multi-byte character is seen in the middle of the response body because
1897 * the remaining bytes of the character have not arrived and read time-out
1898 * occurs, the transfer_timeout exception will be raised instead.
1899 * The exception can be handled and the read operation can be retried
1900 * at a later time.
1901 * When the "Content-Type" response header specifies the character set
1902 * of the response body and the character set is unknown to or unsupported by
1903 * Oracle, the "ORA-01482: unsupported character set" exception will be
1904 * raised if the user tries to read the response body as text. The user
1905 * may either read the response body as binary using the read_raw procedure,
1906 * or set the character set of the response body explicitly using the
1907 * set_body_charset procedure and read the response body as text again.
1908 */
1909 PROCEDURE read_line(r IN OUT NOCOPY resp,
1910 data OUT NOCOPY VARCHAR2 CHARACTER SET ANY_CS,
1911 remove_crlf IN BOOLEAN DEFAULT FALSE);
1912 PRAGMA restrict_references(read_line, wnds, rnds, trust);
1913
1914 /**
1915 * Reads the HTTP response body in binary form and returns the output in
1916 * the caller-supplied buffer. The end_of_body exception will be raised if
1917 * the end of the HTTP response body is reached.
1918 *
1919 * PARAMETERS
1920 * r The HTTP response
1921 * data The HTTP response body in binary form
1922 * len The maximum number of bytes of data to read. If len is
1923 * NULL, this procedure will read as much input as possible to
1924 * fill the buffer allocated in data. The actual amount of
1925 * data returned may be less than that specified if not so
1926 * much data is available before the end of the HTTP response
1927 * body is reached or the transfer_timeout amount of time has
1928 * elapsed. The default is NULL.
1929 *
1930 * EXCEPTIONS
1931 * end_of_body when no data can be returned because the end of
1932 * response body is reached.
1933 *
1934 * When detailed-exception is disabled:
1935 * request_failed the request fails to execute
1936 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1937 * get the detailed error message)
1938 *
1939 * When detailed-exception is enabled:
1940 * bad_argument when some of the arguments passed are not valid.
1941 * transfer_timeout no data is read and a read time-out occurred.
1942 * - plus miscellaneous network or runtime exceptions.
1943 * NOTES
1944 * The UTL_HTTP package supports HTTP 1.1 chunked transfer-encoding.
1945 * When the response body is returned in chunked transfer-encoding format
1946 * as indicated in the response header, the package automatically decodes
1947 * the chunks and return the response body in "dechunked" format.
1948 * If transfer time-out is set in the request of this response, this
1949 * procedure will wait for each data packet to be ready to read until
1950 * time-out occurs. If it occurs, this procedure will stop reading and
1951 * return all the data read successfully. If no data is read successfully,
1952 * the transfer_timeout exception will be raised. The exception can be
1953 * handled and the read operation can be retried at a later time.
1954 */
1955 PROCEDURE read_raw(r IN OUT NOCOPY resp,
1956 data OUT NOCOPY RAW,
1957 len IN PLS_INTEGER DEFAULT NULL);
1958 PRAGMA restrict_references(read_raw, wnds, rnds, trust);
1959
1960 /**
1961 * Ends the HTTP response. This completes the HTTP request and response.
1965 * PARAMETERS
1962 * Unless HTTP 1.1 persistent connection is used in this request, the
1963 * network connection will also be closed.
1964 *
1966 * r The HTTP response
1967 *
1968 * EXCEPTIONS
1969 *
1970 * When detailed-exception is disabled:
1971 * request_failed the request fails to execute
1972 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
1973 * get the detailed error message)
1974 *
1975 * When detailed-exception is enabled:
1976 * bad_argument when some of the arguments passed are not valid.
1977 * - plus miscellaneous network or runtime exceptions.
1978 * NOTES
1979 * None.
1980 */
1981 PROCEDURE end_response(r IN OUT NOCOPY resp);
1982 PRAGMA restrict_references(end_response, wnds, rnds, trust);
1983
1984 /*----------------------- Cookies Management API ------------------------*/
1985 /* The following set of API manipulate the HTTP cookies maintained by the
1986 * database user session.
1987 */
1988
1989 /**
1990 * Returns the number of cookies maintained either in a request context or
1991 * in the UTL_HTTP package's session state.
1992 *
1993 * PARAMETERS
1994 * request_context The request context to return the cookie count for.
1995 * If NULL, the cookie count maintained in the UTL_HTTP
1996 * package's session state will be returned instead.
1997 *
1998 * EXCEPTIONS
1999 * miscellaneous runtime exceptions.
2000 * NOTES
2001 * None.
2002 */
2003 FUNCTION get_cookie_count(request_context IN request_context_key DEFAULT NULL)
2004 RETURN PLS_INTEGER;
2005 PRAGMA restrict_references(get_cookie_count, wnds, rnds, trust);
2006
2007 /**
2008 * Returns all the cookies maintained either in a request context or
2009 * in the UTL_HTTP package's session state.
2010 *
2011 * PARAMETERS
2012 * cookies The cookies returned.
2013 * request_context The request context to return the cookies for. If NULL,
2014 * the cookies maintained in the UTL_HTTP package's session
2015 * state will be returned instead.
2016 *
2017 * EXCEPTIONS
2018 * miscellaneous runtime exceptions.
2019 * NOTES
2020 * None.
2021 */
2022 PROCEDURE get_cookies(cookies IN OUT NOCOPY cookie_table,
2023 request_context IN request_context_key DEFAULT NULL);
2024 PRAGMA restrict_references(get_cookies, wnds, rnds, trust);
2025
2026 /**
2027 * Add the cookies either to a request context or to the UTL_HTTP package's
2028 * session state.
2029 *
2030 * PARAMETERS
2031 * cookies The cookies to be added.
2032 * request_context The request context to add the cookies. If NULL,
2033 * the cookies will be added to the UTL_HTTP package's
2034 * session state instead.
2035 *
2036 * EXCEPTIONS
2037 * miscellaneous runtime exceptions.
2038 * NOTES
2039 * The cookies that the package currently maintains will be not cleared
2040 * before the new cookies are added.
2041 */
2042 PROCEDURE add_cookies(cookies IN cookie_table,
2043 request_context IN request_context_key DEFAULT NULL);
2044 PRAGMA restrict_references(add_cookies, wnds, rnds, trust);
2045
2046 /**
2047 * Clears all the cookies maintained either in a request context or
2048 * in the UTL_HTTP package's session state.
2049 *
2050 * PARAMETERS
2051 * request_context The request context to clear the cookies. If NULL,
2052 * the cookies maintained in the UTL_HTTP package's
2053 * session state will be cleared instead.
2054 *
2055 * EXCEPTIONS
2056 * miscellaneous runtime exceptions.
2057 */
2058 PROCEDURE clear_cookies(request_context IN request_context_key DEFAULT NULL);
2059 PRAGMA restrict_references(clear_cookies, wnds, rnds, trust);
2060
2061 /*---------------- Persistent Connection Management API -----------------*/
2062 /* The following set of API manipulate the HTTP persistent connections
2063 * maintained by the database user session.
2064 */
2065
2066 /**
2067 * Returns the number of network connections currently kept persistent by
2068 * the UTL_HTTP package to the Web servers.
2069 *
2070 * PARAMETERS
2071 * None.
2072 *
2073 * EXCEPTIONS
2074 * miscellaneous runtime exceptions.
2075 * NOTES
2076 * Connections to the same Web server at different TCP/IP ports are
2077 * counted individually. The host names of the Web servers are identified
2078 * as specified in the URL of the original HTTP requests. Therefore,
2079 * fully-qualified host names with domain names will be counted differently
2080 * from the host names without domain names.
2081 */
2082 FUNCTION get_persistent_conn_count RETURN PLS_INTEGER;
2083 PRAGMA restrict_references(get_persistent_conn_count, wnds, rnds, trust);
2084
2085 /**
2086 * Returns all the network connections currently kept persistent by the
2087 * UTL_HTTP package to the Web servers.
2088 *
2089 * PARAMETERS
2090 * connections The network connections currently kept persistent
2091 *
2092 * EXCEPTIONS
2093 * miscellaneous runtime exceptions.
2094 * NOTES
2095 * Connections to the same Web server at different TCP/IP ports are
2099 * from the host names without domain names.
2096 * counted individually. The host names of the Web servers are identified
2097 * as specified in the URL of the original HTTP requests. Therefore,
2098 * fully-qualified host names with domain names will be counted differently
2100 */
2101 PROCEDURE get_persistent_conns(connections IN OUT NOCOPY connection_table);
2102 PRAGMA restrict_references(get_persistent_conns, wnds, rnds, trust);
2103
2104 /**
2105 * Closes a HTTP persistent connection maintained by the UTL_HTTP package
2106 * in the current database session.
2107 *
2108 * PARAMETERS
2109 * conn The HTTP persistent connection to close.
2110 * EXCEPTIONS
2111 * miscellaneous runtime exceptions.
2112 * NOTES
2113 * Connections to the same Web server at different TCP/IP ports are
2114 * counted individually. The host names of the Web servers are identified
2115 * as specified in the URL of the original HTTP requests. Therefore,
2116 * fully-qualified host names with domain names will be counted differently
2117 * from the host names without domain names.
2118 */
2119 PROCEDURE close_persistent_conn(conn IN connection);
2120 PRAGMA restrict_references(close_persistent_conn, wnds, rnds, trust);
2121
2122 /**
2123 * Closes a group of HTTP persistent connections maintained by
2124 * the UTL_HTTP package in the current database session. This procedure
2125 * uses a pattern-match approach to decide which persistent connections
2126 * to close.
2127 *
2128 * To close a group of HTTP persistent connection that share a common
2129 * property (for example, all connections to a particular host, or all
2130 * SSL connections), set the particular parameter(s) and leave the rest
2131 * parameters NULL. If a particular parameter set to NULL when this procedure
2132 * is called, that parameter will not be used to decide which connections
2133 * to close (namely, the caller does not care that value).
2134 *
2135 * For example, the following call to the procedure closes all persistent
2136 * connections (SSL or non) to foobar
2137 *
2138 * utl_http.close_persistent_conns(host => 'foobar');,
2139 *
2140 * And the following call to the procedure closes all persistent connections
2141 * (SSL or non) via the proxy www-proxy at TCP/IP port 80
2142 *
2143 * utl_http.close_persistent_conns(proxy_host => 'foobar',
2144 * proxy_port => 80);
2145 *
2146 * And the following call to the procedure closes all persistent connections
2147 *
2148 * utl_http.close_persistent_conns;
2149 *
2150 * PARAMETERS
2151 * host The host for which persistent connections are to be closed.
2152 * port The port number for which persistent connections are to be
2153 * closed.
2154 * proxy_host The proxy host for which persistent connections are to be
2155 * closed.
2156 * proxy_host The proxy port for which persistent connections are to be
2157 * closed.
2158 * ssl Close persistent SSL connection or non.
2159 * EXCEPTIONS
2160 * miscellaneous runtime exceptions.
2161 * NOTES
2162 * Connections to the same Web server at different TCP/IP ports are
2163 * counted individually. The host names of the Web servers are identified
2164 * as specified in the URL of the original HTTP requests. Therefore,
2165 * fully-qualified host names with domain names will be counted differently
2166 * from the host names without domain names.
2167 *
2168 * Note that the use of a NULL value in a parameter when this procedure
2169 * is called means that the caller does not care its value when the package
2170 * decides which persistent connection to close. In the event that you
2171 * want a NULL value in a parameter to match only a NULL value of the
2172 * parameter of a persistent connection (which is when you want to close
2173 * a specific persistent connection), you should use the
2174 * close_persistent_conn procedure that closes a specific persistent
2175 * connection.
2176 */
2177 PROCEDURE close_persistent_conns(host IN VARCHAR2 DEFAULT NULL,
2178 port IN PLS_INTEGER DEFAULT NULL,
2179 proxy_host IN VARCHAR2 DEFAULT NULL,
2180 proxy_port IN PLS_INTEGER DEFAULT NULL,
2181 ssl IN BOOLEAN DEFAULT NULL);
2182 PRAGMA restrict_references(close_persistent_conns, wnds, rnds, trust);
2183
2184 /*--------------------- Last Detailed Exception API ---------------------*/
2185 /* This set of API return the last detailed exception when detailed exception
2186 * is disabled.
2187 */
2188
2189 /**
2190 * Retrieves the detailed SQLCODE of the last exception raised.
2191 *
2192 * PARAMETERS
2193 * None.
2194 *
2195 * EXCEPTIONS
2196 * miscellaneous runtime exceptions.
2197 * NOTES
2198 * None.
2199 */
2200 FUNCTION get_detailed_sqlcode RETURN PLS_INTEGER;
2201 PRAGMA restrict_references(get_detailed_sqlcode, wnds, rnds, trust);
2202
2203 /**
2204 * Retrieves the detailed SQLERRM of the last exception raised.
2205 *
2206 * PARAMETERS
2207 * None.
2208 *
2209 * EXCEPTIONS
2210 * miscellaneous runtime exceptions.
2211 * NOTES
2212 * None.
2213 */
2214 FUNCTION get_detailed_sqlerrm RETURN VARCHAR2;
2215 PRAGMA restrict_references(get_detailed_sqlerrm, wnds, rnds, trust);
2216
2220 * of the page at most.
2217 /*------------------------- Simple Fetch API ----------------------------*/
2218 /**
2219 * Fetches a Web page. This function returns the first 2000 bytes
2221 *
2222 * PARAMETERS
2223 * url The URL of the Web page
2224 * proxy The proxy host and port number. See set_proxy for the
2225 * format of the proxy string. If proxy is NULL, the
2226 * proxy session of the current session will be used.
2227 * wallet_path The path of the Oracle wallet. The format is
2228 * 'file:/<wallet-directory-path>'. If wallet_path
2229 * is NULL, the wallet set for the current session will
2230 * be used.
2231 * wallet_password The password needed to open the wallet. There may a
2232 * second copy of a wallet in a wallet directory that
2233 * may be opened without a password. That second copy of
2234 * the wallet is for read only. If password is NULL, the
2235 * UTL_HTTP package will open the second, read-only copy
2236 * of the wallet instead. See the documentation on Oracle
2237 * wallets for details. If a password
2238 * is required to open the wallet, it must be given
2239 * explicitly. This function will NOT use the password
2240 * set previously with set_wallet.
2241 *
2242 * request_failed the request fails to execute
2243 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
2244 * get the detailed error message)
2245 *
2246 * When detailed-exception is enabled:
2247 *
2248 * bad_argument when some of the arguments passed are not valid.
2249 * bad_url when the URL is not valid.
2250 * unknown_scheme when the request scheme is not known.
2251 * too_many_requests when there are too many open requests.
2252 * - plus miscellaneous network and runtime exceptions.
2253 * NOTES
2254 * - The URL passed as an argument to this function will not be examined
2255 * for illegal characters per the URL specification RFC 2396, like spaces
2256 * for example. The caller should escape those characters with the UTL_URL
2257 * package. See the comments of the package for the list of legal
2258 * characters in URLs. Note that URLs should consist of US-ASCII
2259 * characters only. The use of non-US-ASCII characters in an URL is
2260 * generally unsafe.
2261 * URL may contain username and password to authenticate the request to
2262 * the server. The general format would be
2263 * <scheme>://[<user>[:<password>]@]<host>[:<port>]/[...].
2264 * - Please see the documentation of the function set_wallet on the use of
2265 * an Oracle wallet, which is required for accessing HTTPS Web servers.
2266 * - Unless response error check is turned on, this function does not raise
2267 * an exception when a 4xx or 5xx response is received from the Web server.
2268 * Instead, it returns the formatted error message from the Web server:
2269 * "<HTML>
2270 * <HEAD>
2271 * <TITLE>Error Message</TITLE>
2272 * </HEAD>
2273 * <BODY>
2274 * <H1>Fatal Error 500</H1>
2275 * Can't Access Document: http://home.nothing.comm.
2276 * <P>
2277 * <B>Reason:</B> Can't locate remote host: home.nothing.comm.
2278 * <P>
2279 *
2280 * <P><HR>
2281 * <ADDRESS><A HREF="http://www.w3.org">
2282 * CERN-HTTPD3.0A</A></ADDRESS>
2283 * </BODY>
2284 * </HTML>"
2285 */
2286 FUNCTION request(url IN VARCHAR2,
2287 proxy in VARCHAR2 DEFAULT NULL,
2288 wallet_path IN VARCHAR2 DEFAULT NULL,
2289 wallet_password IN VARCHAR2 DEFAULT NULL)
2290 RETURN VARCHAR2;
2291 PRAGMA restrict_references (request, wnds, rnds, wnps, rnps, trust);
2292
2293 /**
2294 * Fetches a Web page. The page is returned in a PL/SQL-table of
2295 * VARCHAR2(2000) pieces.
2296 *
2297 * The elements of the PLSQL-table returned by request_pieces are
2298 * successive pieces of the data obtained from the HTTP request to that
2299 * URL. Here is a typical URL:
2300 * http://www.oracle.com
2301 * So a call to request_pieces could look like the example below. Note the
2302 * use of the plsql-table method COUNT to discover the number of pieces
2303 * returned, which may be zero or more:
2304 *
2305 * declare
2306 * pieces utl_http.html_pieces;
2307 * begin
2308 * pieces := utl_http.request_pieces('http://www.oracle.com/');
2309 * for i in 1 .. pieces.count loop
2310 * .... -- process each piece
2311 * end loop;
2312 * end;
2313 *
2314 * PARAMETERS
2315 * url The URL of the Web page
2316 * max_pieces The maximum number of VARCHAR2 pieces to retrieve
2317 * proxy The proxy host and port number. See set_proxy for the
2318 * format of the proxy string. If proxy is NULL, the
2319 * proxy session of the current session will be used.
2320 * wallet_path The path of the Oracle wallet. The format is
2321 * 'file:/<wallet-directory-path>'. If wallet_path
2322 * is NULL, the wallet set for the current session will
2323 * be used.
2324 * wallet_password The password needed to open the wallet. There may a
2325 * second copy of a wallet in a wallet directory that
2329 * of the wallet instead. See the documentation on Oracle
2326 * may be opened without a password. That second copy of
2327 * the wallet is for read only. If password is NULL, the
2328 * UTL_HTTP package will open the second, read-only copy
2330 * wallets for details. If a password
2331 * is required to open the wallet, it must be given
2332 * explicitly. This function will NOT use the password
2333 * set previously with set_wallet.
2334 *
2335 * request_failed the request fails to execute
2336 * (use get_detailed_sqlcode and get_detailed_sqlerrm to
2337 * get the detailed error message)
2338 *
2339 * When detailed-exception is enabled:
2340 *
2341 * bad_argument when some of the arguments passed are not valid.
2342 * bad_url when the URL is not valid.
2343 * unknown_scheme when the request scheme is not known.
2344 * too_many_requests when there are too many open requests.
2345 * - plus miscellaneous network and runtime exceptions.
2346 * NOTES
2347 * - The URL passed as an argument to this function will not be examined
2348 * for illegal characters per the URL specification RFC 2396, like spaces
2349 * for example. The caller should escape those characters with the UTL_URL
2350 * package. See the comments of the package for the list of legal
2351 * characters in URLs. Note that URLs should consist of US-ASCII
2352 * characters only. The use of non-US-ASCII characters in an URL is
2353 * generally unsafe.
2354 * URL may contain username and password to authenticate the request to
2355 * the server. The general format would be
2356 * <scheme>://[<user>[:<password>]@]<host>[:<port>]/[...].
2357 * - Each entry of the PL/SQL table (the "pieces") returned by this function
2358 * may not be filled to their fullest capacity. The function may
2359 * start filling the data in the next "piece" before the previous "piece"
2360 * is totally full.
2361 * - Please see the documentation of the function set_wallet on the use of
2362 * an Oracle wallet, which is required for accessing HTTPS Web servers.
2363 * - Unless response error check is turned on, this function does not raise
2364 * an exception when a 4xx or 5xx response is received from the Web server
2365 * Instead, it returns the formatted error message from the Web server:
2366 * "<HTML>
2367 * <HEAD>
2368 * <TITLE>Error Message</TITLE>
2369 * </HEAD>
2370 * <BODY>
2371 * <H1>Fatal Error 500</H1>
2372 * Can't Access Document: http://home.nothing.comm.
2373 * <P>
2374 * <B>Reason:</B> Can't locate remote host: home.nothing.comm.
2375 * <P>
2376 *
2377 * <P><HR>
2378 * <ADDRESS><A HREF="http://www.w3.org">
2379 * CERN-HTTPD3.0A</A></ADDRESS>
2380 * </BODY>
2381 * </HTML>"
2382 */
2383 FUNCTION request_pieces(url IN VARCHAR2,
2384 max_pieces IN NATURAL DEFAULT 32767,
2385 proxy in VARCHAR2 DEFAULT NULL,
2386 wallet_path IN VARCHAR2 DEFAULT NULL,
2387 wallet_password IN VARCHAR2 DEFAULT NULL)
2388 RETURN html_pieces;
2389 PRAGMA restrict_references (request_pieces, wnds, rnds, wnps, rnps, trust);
2390
2391 /**
2392 * Sets the default content-encoding support for the specified encoding
2393 * scheme for all future HTTP requests.
2394 *
2395 * PARAMETERS
2396 * scheme The encoding scheme
2397 * enable Enable the support or not
2398 *
2399 * EXCEPTIONS
2400 * miscellaneous runtime exceptions.
2401 * NOTES
2402 * Only the "gzip" encoding scheme is currently supported.
2403 */
2404 PROCEDURE set_content_encoding_support(scheme IN VARCHAR2,
2405 enable IN BOOLEAN DEFAULT FALSE);
2406 PRAGMA restrict_references(set_content_encoding_support, wnds, rnds, trust);
2407
2408 /**
2409 * Retrieves the default content-encoding support for the specified encoding
2410 * scheme for all future HTTP requests.
2411 *
2412 * PARAMETERS
2413 * scheme The encoding scheme
2414 * enable The support is enabled or not
2415 *
2416 * EXCEPTIONS
2417 * miscellaneous runtime exceptions.
2418 * NOTES
2419 * Only the "gzip" encoding scheme is currently supported.
2420 */
2421 PROCEDURE get_content_encoding_support(scheme IN VARCHAR2,
2422 enable OUT BOOLEAN);
2423 PRAGMA restrict_references(get_content_encoding_support, wnds, rnds, trust);
2424
2425 /**
2426 * Sets the content-encoding support for the specified encoding scheme for
2427 * this HTTP request.
2428 *
2429 * PARAMETERS
2430 * r The HTTP request
2431 * scheme The encoding scheme
2432 * enable Enable the support or not
2433 *
2434 * EXCEPTIONS
2435 * miscellaneous runtime exceptions.
2436 * NOTES
2437 * None.
2438 */
2439 PROCEDURE set_content_encoding_support(r IN OUT NOCOPY req,
2440 scheme IN VARCHAR2,
2441 enable IN BOOLEAN DEFAULT FALSE);
2442 PRAGMA restrict_references(set_content_encoding_support, wnds, rnds, trust);
2443
2444 /**
2445 * Sets whether get_response should raise an exception when the Web server
2446 * returns a status code that indicates an error (namely, a status code in
2447 * the 4xx or 5xx ranges). For example, when the requested URL is not found
2448 * in the destination Web server, a 404 (document not found) response status
2449 * code is returned. In general, a 4xx or 5xx response is considered an
2450 * error response. If response error check is set, get_response will raise
2451 * the HTTP_CLIENT_ERROR or HTTP_SERVER_ERROR exception if the status code
2452 * indicates an error. Otherwise, get_response will not raise the exception
2453 * if the status codes indicates an error. Response error check is turned off
2454 * by default.
2455 *
2456 * PARAMETERS
2457 * enable Set to TRUE to check for response error. FALSE otherwise.
2458 *
2459 * EXCEPTIONS
2460 * miscellaneous runtime exceptions.
2461 * NOTES
2462 * None.
2463 */
2464 PROCEDURE set_response_error_check(r IN OUT NOCOPY req,
2465 enable IN BOOLEAN DEFAULT FALSE);
2466 PRAGMA restrict_references(set_response_error_check, wnds, rnds, trust);
2467
2468 END utl_http;
[Home] [Help]