1 PACKAGE fnd_gfm AUTHID CURRENT_USER AS
2 /* $Header: AFGFMS.pls 120.11 2011/08/22 16:26:49 ctilley ship $ */
3
4 ------------------------------------------------------------------------------
5 /*
6 * authenticate - validate an access key
7 */
8 FUNCTION authenticate(access_id in NUMBER,
9 file_id in NUMBER default -1) RETURN boolean;
10 ------------------------------------------------------------------------------
11 /*
12 * authorize - generate an authorized access key good for one day.
13 * This function is called to generate an access number that will
14 * be accepted by the GFM cartridge as authorization of the indicated
15 * operation. The access number should be presented as part of the
16 * URL used to invoke the cartridge.
17 *
18 * file_id For downloads, the file identifier of the LOB to download;
19 * for uploads, this should be NULL.
20 */
21 FUNCTION authorize(file_id NUMBER) RETURN NUMBER;
22
23 ------------------------------------------------------------------------------
24 /*
25 * construct_download_URL2 - construct a download URL
26 * This function constructs a URL that may be presented to a client
27 * browser in order to download the indicated file. This function
28 * contains knowledge of the syntax of the required URL, but does
29 * require the web server's location, and PL/SQL agent's name to be
30 * known. The function uses the authorize function described above
31 * to provide access. The function returns the constructed URL.
32 * Optionally, this routine can be told to automatically commit
33 * the authorization step which is necessary before the URL can be
34 * viewed.
35 *
36 * gfm_agent Value of the Generic File Manager agent with a
37 * trailing slash.
38 * file_id The file identifier of the LOB to download.
39 * purge_on_view Set to TRUE if the LOB should be purged from
40 * the database after it has been downloaded. If
41 * this is set, the expiration date is also
42 * marked to be in the near future, so the file
43 * is eventually purged whether or not the
44 * download succeeds.
45 * autocommit If TRUE, the routine will automatically commit
46 * the generated access key so the caller does not
47 * need to. -- This is not required in 11.5, since
48 * we use AUTONOMOUS TRANSACTIONS. ---
49 * modplsql If TRUE then reterives the MODPL/SQL catridge
50 * URL for download.
51 */
52 FUNCTION construct_download_URL2(gfm_agent VARCHAR2,
53 file_id NUMBER,
54 purge_on_view BOOLEAN DEFAULT FALSE,
55 modplsql BOOLEAN DEFAULT FALSE,
56 authenticate BOOLEAN DEFAULT TRUE)
57 RETURN VARCHAR2;
58 ------------------------------------------------------------------------------
59 /*
60 * construct_upload_URL - construct a upload URL
61 * This function constructs a URL that may be embedded in a form
62 * action in order to upload a file type field. This function
63 * contains knowledge of the syntax of the required URL, but does
64 * require the web server's location, and PL/SQL agent's name to be
65 * known, as well as the access_id generated using the authorize
66 * function described above. The function returns the constructed URL.
67 *
68 * gfm_agent Value of the Generic File Manager agent with a
69 * trailing slash.
70 * proc Procedure to run
71 * access_id Authentication key as generated by fnd_gfm.authorize
72 */
73 FUNCTION construct_upload_URL(gfm_agent VARCHAR2,
74 proc VARCHAR2,
75 access_id NUMBER)
76 RETURN VARCHAR2;
77 ------------------------------------------------------------------------------
78
79 /*
80 * construct_download_URL - construct a download URL
81 * This function constructs a URL that may be presented to a client
82 * browser in order to download the indicated file. This function
83 * contains knowledge of the syntax of the required URL, but does
84 * require the web server's location, and PL/SQL agent's name to be
85 * known. The function uses the authorize function described above
86 * to provide access. The function returns the constructed URL.
87 * Optionally, this routine can be told to automatically commit
88 * the authorization step which is necessary before the URL can be
89 * viewed.
90 *
91 * gfm_agent Value of the Generic File Manager agent with a
92 * trailing slash.
93 * file_id The file identifier of the LOB to download.
94 * purge_on_view To set expiry date for the record or not
95 */
96 FUNCTION construct_download_URL(gfm_agent VARCHAR2,
97 file_id NUMBER,
98 purge_on_view BOOLEAN DEFAULT FALSE)
99 RETURN VARCHAR2;
100 ------------------------------------------------------------------------------
101 /*
102 * construct_get_URL - construct a get request URL
103 * This function constructs a URL that may be presented to a client
104 * browser in order to get the indicated file. This function
105 * contains knowledge of the syntax of the required URL, but does
106 * require the web server's location, and PL/SQL agent's name to be
107 * known. The function returns the constructed URL.
108 *
109 * gfm_agent Value of the Generic File Manager agent with a
110 * trailing slash.
111 * proc Procedure to run
112 * path Arg path
113 */
114 FUNCTION construct_get_url(gfm_agent varchar2,
115 proc varchar2,
116 path varchar2)
117 return varchar2;
118 ------------------------------------------------------------------------------
119 /*
120 * construct_relative_get - construct a relative get request URL
121 * fragment without the plsql_agent/dad info.
122 *
123 * This function constructs a URL that may be presented to the browser
124 * as a relative url to a document that has already been "gotten".
125 *
126 * proc Procedure to run
127 * path Arg path
128 */
129 FUNCTION construct_relative_get(proc varchar2,
130 path varchar2)
131 return varchar2;
132 ------------------------------------------------------------------------------
133 /*
134 * confirm_upload - confirm the completion of an upload
135 * This procedure must be called from within the user's PL/SQL upload
136 * procedure to authenticate the upload and move the blob into the
137 * fnd_lobs table. The new generated file_id is returned to the caller.
138 *
139 * access_id The access identifier that authorized the upload
140 * file_name The file_name as stored in the fnd_lobs_document table
141 * by WebDB...the value of the file type input field.
142 * program_name The application short name to record
143 * program_tag The application tag to record
144 * expiration_date The expiration date to record; typically, this is null
145 * which means that the LOB never expires, but must be
146 * explicitly deleted
147 * language The document language; defaults to userenv('LANG')
148 * wakeup If TRUE, indicates that wait_for_upload is expected to
149 * be called on the original authorization key; the GFM
150 * can associate the given file identifier to the original
151 * authorization key and wake up the identified waiter.
152 */
153 FUNCTION confirm_upload(
154 access_id NUMBER,
155 file_name VARCHAR2,
156 program_name VARCHAR2 DEFAULT NULL,
157 program_tag VARCHAR2 DEFAULT NULL,
158 expiration_date DATE DEFAULT NULL,
159 language VARCHAR2 DEFAULT userenv('LANG'),
160 wakeup BOOLEAN DEFAULT FALSE )
161 RETURN NUMBER;
162 ------------------------------------------------------------------------------
163 /*
164 * dispatch
165 * This procedure takes a single argument in the form of
166 * <proc>/<arg>
167 *
168 * and executes the proc, passing the single arg.
169 *
170 * p_path the proc and arg to call
171 */
172 PROCEDURE dispatch(p_path varchar2);
173 ------------------------------------------------------------------------------
174 /*
175 * get_file_id
176 * This function retrieves the file_id for the corresponding access_id
177 * from the fnd_lob_access table.
178 *
179 * access_id the access id
180 */
181 FUNCTION get_file_id(access_id NUMBER) RETURN NUMBER;
182 ------------------------------------------------------------------------------
183 /*
184 * wait_for_upload - wait for upload confirmation
185 * This procedure blocks the caller using the DBMS event facilities,
186 * and sleeps until the confirm_upload procedure is invoked to confirm
187 * that the intended LOB has indeed been uploaded, or until timeout
188 * seconds has elapsed.
189 *
190 * access_id The access id returned by the authorize function;
191 * timeout The maximum number of seconds to wait for the upload
192 * to complete.
193 * file_id The file identifier of the new LOB; if this is null,
194 * the wait timed out without receiving confirmation.
195 */
196 PROCEDURE wait_for_upload(access_id NUMBER, timeout NUMBER,
197 file_id OUT NOCOPY NUMBER);
198 ------------------------------------------------------------------------------
199 /*
200 * purge_expired - purge all expired rows in GFM tables
201 * It is expected that this procedure will be called on a periodic
202 * basis in order to flush the GFM tables of expired information.
203 */
204 PROCEDURE purge_expired(program_name VARCHAR2 DEFAULT NULL);
205 ------------------------------------------------------------------------------
206 /*
207 * purge_set - purge selected rows from the LOB table
208 * This procedure is called by programs wishing to clear out segments
209 * of the LOB table, usually when a program is deinstalled or otherwise
210 * becomes unavailable.
211 *
212 * program_name A string matched against the program_name column
213 * program_tag A string matched against the program_tag column
214 *
215 * If the program tag is omitted, then all rows matching the program
216 * name are purged.
217 */
218 PROCEDURE purge_set(program_name VARCHAR2,
219 program_tag VARCHAR2 DEFAULT NULL);
220 ------------------------------------------------------------------------------
221 /*
222 * purge - CM cover routine for purge_set and purge_expired
223 */
224 PROCEDURE purge(errbuf out NOCOPY varchar2,
225 retcode out NOCOPY varchar2,
226 expired varchar2 default 'Y',
227 program_name varchar2 default null,
228 program_tag varchar2 default null);
229 ------------------------------------------------------------------------------
230 ------------------------------------------------------------------------------
231 ------------------------------------------------------------------------------
232 /*
233 * The GFM allows new "files" to be created and written to directly
234 * rather than always through the indirect means of file upload. This
235 * allows programs written in PL/SQL to "spool" their output to a GFM
236 * file rather than to a local file. Files are identified by a file
237 * handle, which is simply a number.
238 *
239 * A file may be created using file_create, then written to using
240 * file_write or file_write_line, and eventually closed using
241 * file_close.
242 */
243 ------------------------------------------------------------------------------
244 /*
245 * file_create - create a new empty file
246 * This function creates a new empty GFM file to which data may be
247 * written. A descriptor for the file is returned that may be used
248 * for subsequent operations performed on the file. The descriptor
249 * is only valid within a single transaction.
250 *
251 * file_name The "name" of the file. This is purely informative
252 * and has no special meaning to the GFM as file iden-
253 * tification is always done through file identifiers.
254 * content_type This string must be a valid entity-header value for
255 * the entity "Content-Type" (see IETF RFC 2045 for
256 * complete information.
257 * program_name The application short name to associate with the file
258 * program_tag The application tag to associate with the file
259 */
260 FUNCTION file_create(file_name VARCHAR2 DEFAULT NULL,
261 content_type VARCHAR2 DEFAULT 'text/plain',
262 program_name VARCHAR2 DEFAULT NULL,
263 program_tag VARCHAR2 DEFAULT NULL) RETURN NUMBER;
264 ------------------------------------------------------------------------------
265 /*
266 * file_close - close a file
267 * This function closes a file previously opened with file_create.
268 * The file identifier of the new LOB is returned. This function
269 * must be called to ensure the file is permanently recorded by the
270 * GFM. The transaction in which the file is written must also
271 * commit following this call.
272 *
273 * fd The file descriptor of the file to close
274 */
275 FUNCTION file_close(fd NUMBER) RETURN NUMBER;
276 ------------------------------------------------------------------------------
277 /*
278 * file_write - write raw data to a file
279 * This procedure writes raw data to an open file. This should be
280 * used only to write files whose media types are not 'text'. The
281 * data will be written exactly as is without processing. The data
282 * is appended to the file.
283 *
284 * fd The file descriptor of the file to which to write
285 * amount The amount of data in the buffer to write
286 * buffer The data to write to the file
287 */
288 PROCEDURE file_write(fd NUMBER, amount BINARY_INTEGER, buffer RAW);
289 ------------------------------------------------------------------------------
290 /*
291 * file_write - write text to a file
292 * This procedure writes the given text to an open file, but does
293 * not include a line terminator. The data is appended to the file.
294 *
295 * fd The file descriptor of the file to which to write
296 * buffer The text to write to the file; this should not
297 * exceed 1000 characters in length
298 */
299 PROCEDURE file_write(fd NUMBER, buffer VARCHAR2);
300 ------------------------------------------------------------------------------
301 /*
302 * file_write_line - write text to a file with a line terminator
303 * This procedure writes the given text followed by a line terminator
304 * to an open file. Line terminators in GFM files require special
305 * representation and this is the only safe mechanism to insert line
306 * terminators into a GFM file whose media type is 'text'. If the
307 * media type is not text, you should use not use this procedure.
308 *
309 * fd The file descriptor of the file to which to write
313 PROCEDURE file_write_line(fd NUMBER, buffer VARCHAR2);
310 * buffer The text to write to the file; this should not
311 * exceed 1000 characters in length; it may be null
312 */
314 ------------------------------------------------------------------------------
315 /*
316 * test - testing procedure
317 * This procedure is used during GFM installation to verify the
318 * configuration of the various software components.
319 */
320 PROCEDURE test;
321 ------------------------------------------------------------------------------
322 /*
323 * download -
324 * This procedure processes a download request
325 */
326 PROCEDURE download(file_id NUMBER, access NUMBER, purge VARCHAR2 DEFAULT NULL);
327 ------------------------------------------------------------------------------
328 /*
329 * get_iso_charset
330 * This procedure is used by fndgfm to retrieve the iso equivalent
331 * of the db's oracle character set.
332 */
333 FUNCTION get_iso_charset RETURN VARCHAR2;
334 ------------------------------------------------------------------------------
335 /*
336 * oracle_to_iana
337 * This procedure retrieves the iana equivalent of the specified oracle
338 * charset
339 */
340 FUNCTION oracle_to_iana(cs varchar2) return varchar2;
341 ------------------------------------------------------------------------------
342 /*
343 * iana_to_oracle
344 * This procedure retrieves the oracle equivalent of the specified iana
345 * charset.
346 */
347 FUNCTION iana_to_oracle(ics varchar2) return varchar2;
348 ------------------------------------------------------------------------------
349 /*
350 ** download_blob
351 ** encapsulate the actual downloading of the blob using webdb
352 */
353 PROCEDURE download_blob(fid number);
354 ------------------------------------------------------------------------------
355 /*
356 * one_time_use_store
357 * Store a value in the FND_LOB_ACCESS table and return a one-time-use
358 * ticket that can be used by one_time_use_retrieve() to fetch the value.
359 */
360 FUNCTION one_time_use_store(value number) return number;
361 ------------------------------------------------------------------------------
362 /*
363 * one_time_use_store
364 * A more secure API with a large entropy.
365 * It returns a string that expires after lifespan
366 * seconds. Opcode is a verification code used
367 * when retrieving ticket value.
368 */
369 FUNCTION ONE_TIME_USE_STORE( VALUE IN VARCHAR2 ,
370 LIFESPAN IN NUMBER DEFAULT NULL,
371 OPCODE IN VARCHAR2 DEFAULT NULL)
372 RETURN VARCHAR2;
373 ------------------------------------------------------------------------------
374 /*
375 * one_time_use_retrieve
376 * Retrieve a value from the FND_LOB_ACCESS table, given a one-time-use
377 * ticket that was generated by one_time_use_store().
378 */
379 FUNCTION one_time_use_retrieve(ticket number) return number;
380 ------------------------------------------------------------------------------
381 /*
382 * one_time_use_retrieve
383 * Retrieves value given a one-time-use
384 * ticket that was generated by one_time_use_store().
385 * if opcode passed, the API verifies the opcode value
386 * against the opcode value passed in one_time_use_store.
387 */
388 FUNCTION ONE_TIME_USE_RETRIEVE( TICKET IN VARCHAR2 ,
389 OPCODE IN VARCHAR2 DEFAULT NULL)
390 RETURN VARCHAR2;
391 ------------------------------------------------------------------------------
392 /*
393 * get -
394 * This procedure processes a download request
395 */
396 PROCEDURE get(p_path varchar2);
397 ------------------------------------------------------------------------------
398 /*
399 * copy_lob - This function copies one lob to another
400 * Returns the file_id of the new lob.
401 */
402 FUNCTION copy_lob(fid_from number) return number;
403 ------------------------------------------------------------------------------
404 /*
405 * set_file_format - This function sets the file_format for fnd_lobs CTX
406 * Returns file_format derived from file_content_type in fnd_lobs.
407 */
408 FUNCTION set_file_format(l_file_content_type VARCHAR2) RETURN VARCHAR2;
409 ------------------------------------------------------------------------------
410 /*
411 * set_file_format - This function sets the file_format for fnd_lobs CTX
412 * Returns file_format derived from file_content_type in fnd_lobs.
413 */
414 PROCEDURE CLOB_TO_BLOB (
415 my_clob clob,
416 file_name varchar2,
417 fid in out nocopy number,
418 file_content_type varchar2 default null,
419 language varchar2 default null,
420 x_return_status OUT NOCOPY Varchar2,
421 x_msg_count OUT NOCOPY Number,
422 x_msg_data OUT NOCOPY Varchar2);
423
424 ------------------------------------------------------------------------------
425 /*
426 * delete_lob - This api delete one record from fnd_lobs according to
427 * the file_id.
428 */
429 PROCEDURE delete_lob(fid number);
430
431 ------------------------------------------------------------------------------
432 /*
433 * getRelease - returns the current major release
434 *
435 */
436 FUNCTION getRelease RETURN NUMBER;
437
441 * verify_file_type
438 ------------------------------------------------------------------------------
439
440 /*
442 * This function indicates if a filetype is valid to be uploaded into fnd_lobs
443 * return value of Y or N
444 */
445 FUNCTION verify_file_type(file_name varchar2 default null, file_ext varchar2 default null) return varchar2;
446
447 ------------------------------------------------------------------------------
448 END fnd_gfm;
[Home] [Help]