Annotation of libwww/Library/src/HTFWrite.html, revision 2.16
2.1 frystyk 1: <HTML>
2: <HEAD>
2.9 frystyk 3: <TITLE>ANSI C FILE Stream</TITLE>
2.15 frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 31-Jan-1996 -->
2.1 frystyk 5: <NEXTID N="z4">
6: </HEAD>
7: <BODY>
8:
2.8 frystyk 9: <H1>Wrting to a File using ANSI C</H1>
2.1 frystyk 10:
11: <PRE>
12: /*
2.4 frystyk 13: ** (c) COPYRIGHT MIT 1995.
2.1 frystyk 14: ** Please first read the full copyright statement in the file COPYRIGH.
15: */
16: </PRE>
17:
18: It is useful to have both FWriter and Writer for environments in which
2.2 frystyk 19: <CODE>fdopen()</CODE> doesn't exist for example. The module contains
20: the following parts:
21:
22: <UL>
2.15 frystyk 23: <LI><A HREF="#utils">Basic Utility Streams</A>
24: <LI><A HREF="#write">An ANSI C File Writer Stream</A>
25: <LI><A HREF="#converters">Various Converters using the File Writer Stream</A>
2.2 frystyk 26: </UL>
27:
2.1 frystyk 28:
2.15 frystyk 29: This module is implemented by <A HREF="HTFWrite.c">HTFWrite.c</A>, and
30: it is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C
31: Reference Library</A>.
2.1 frystyk 32:
33:
34: <PRE>
35: #ifndef HTFWRITE_H
36: #define HTFWRITE_H
37:
38: #include "HTStream.h"
39: #include "HTFormat.h"
40: </PRE>
41:
2.15 frystyk 42: <A NAME="utils"><H2>Basic Utility Streams</H2></A>
2.14 frystyk 43:
2.15 frystyk 44: These streams can be plugged in everywhere in a stream pipe.
2.14 frystyk 45:
46: <H3><A NAME="BlackHole">Black Hole Stream</A></H3>
2.2 frystyk 47:
2.15 frystyk 48: This stream simply absorbs data without doing anything what so
49: ever. The <CODE>HTBlackHoleConverter</CODE> declaration can be used in
50: the stream stack as a converter.
2.2 frystyk 51:
52: <PRE>
2.13 frystyk 53: extern HTStream * HTBlackHole (void);
2.14 frystyk 54: extern HTConverter HTBlackHoleConverter;
55: </PRE>
56:
57: <H3>Through Line</H3>
58:
59: This stream just pumps data right through.
60:
61: <PRE>
62: extern HTConverter HTThroughLine;
2.2 frystyk 63: </PRE>
64:
2.15 frystyk 65: <H3>Generic Error Stream</H3>
2.1 frystyk 66:
2.15 frystyk 67: The Error stream simply returns HT_ERROR on all methods. This can be
68: used to stop a stream as soon as data arrives, for example from the
69: network.
70:
71: <PRE>
72: extern HTStream * HTErrorStream (void);
73: </PRE>
74:
75: <H2><A NAME="write">An ANSI C File Writer Stream</A></H2>
76:
77: This function puts up a new stream given an open file descripter. If the file
78: is not to be closed afterwards, then set leave_open = NO.
79:
80: <PRE>
81: extern HTStream * HTFWriter_new (HTRequest * request,
82: FILE * fp,
83: BOOL leave_open);
84: </PRE>
85:
86: <A NAME="converters"><H2>Various Converters using the File Writer
87: Stream</H2></A>
88:
89: This is a set of functions that can be registered as converters. They
90: all use the basic ANSI C file writer stream for writing out to the
91: local file system.
2.1 frystyk 92:
2.5 frystyk 93: <PRE>
2.14 frystyk 94: extern HTConverter HTSaveAndExecute, HTSaveLocally, HTSaveAndCallback;
2.1 frystyk 95: </PRE>
96:
2.15 frystyk 97: <DL>
2.1 frystyk 98:
2.15 frystyk 99: <DT><CODE>HTSaveLocally</CODE>
100: <DD>Saves a file to local disk. This can for example be used to dump
101: date objects of unknown media types to local disk. The stream prompts
102: for a file name for the temporary file.
103:
104: <DT><CODE>HTSaveAndExecute</CODE>
105:
106: <DD>Creates temporary file, writes to it and then executes system
107: command (maybe an external viewer) when EOF has been reached. The
108: stream finds a suitable name of the temporary file which preserves the
109: suffix. This way, the system command can find out the file type from
110: the name of the temporary file name.
111:
112: <DT><CODE>HTSaveAndCallback</CODE>
113:
114: <DD>This stream works exactly like the <CODE>HTSaveAndExecute</CODE>
115: stream but in addition when EOF has been reached, it checks whether a
116: callback function has been associated with the request object in which
117: case, this callback is being called. This can be use by the
118: application to do some processing <EM>after</EM> the system command
119: has terminated. The callback function is called with the file name of
120: the temporary file as parameter.
121:
122: </DL>
123:
124: <A NAME="tmp"><H3>Location of Temporary Files</H3></A>
125:
126: The destination for temporary files can be managed by the following
2.2 frystyk 127: functions:
128:
129: <PRE>
2.16 ! frystyk 130: extern BOOL HTTmp_setRoot (const char * tmp_root);
! 131: extern const char * HTTmp_getRoot (void);
2.13 frystyk 132: extern void HTTmp_freeRoot (void);
2.2 frystyk 133: </PRE>
134:
135: The <CODE>HTTmp_freeRoot</CODE> is called by the <A
2.11 frystyk 136: HREF="HTReq.html#Library">HTLibTerminate</A> function. The default
2.13 frystyk 137: value is defined in <A HREF="HTAccess.html#Addresses">HTReq.html</A>
2.1 frystyk 138:
2.8 frystyk 139: <PRE>
2.1 frystyk 140: #endif
141: </PRE>
142:
2.8 frystyk 143: End of declaration module
2.1 frystyk 144: </BODY>
145: </HTML>
Webmaster