1QNPInstance(3qt)                                              QNPInstance(3qt)
2
3
4

NAME

6       QNPInstance - QObject that is a web browser plugin
7

SYNOPSIS

9       This class is part of the Qt Netscape Extension.
10
11       #include <qnp.h>
12
13       Inherits QObject.
14
15   Public Members
16       ~QNPInstance ()
17       int argc () const
18       const char * argn ( int i ) const
19       const char * argv ( int i ) const
20       enum Reason { ReasonDone = 0, ReasonBreak = 1, ReasonError = 2,
21           ReasonUnknown = -1 }
22       const char * arg ( const char * name ) const
23       enum InstanceMode { Embed = 1, Full = 2, Background = 3 }
24       InstanceMode mode () const
25       const char * userAgent () const
26       virtual QNPWidget * newWindow ()
27       QNPWidget * widget ()
28       enum StreamMode { Normal = 1, Seek = 2, AsFile = 3, AsFileOnly = 4 }
29       virtual bool newStreamCreated ( QNPStream *, StreamMode & smode )
30       virtual int writeReady ( QNPStream * )
31       virtual int write ( QNPStream *, int offset, int len, void * buffer )
32       virtual void streamDestroyed ( QNPStream * )
33       void status ( const char * msg )
34       void getURLNotify ( const char * url, const char * window = 0, void *
35           data = 0 )
36       void getURL ( const char * url, const char * window = 0 )
37       void postURL ( const char * url, const char * window, uint len, const
38           char * buf, bool file )
39       QNPStream * newStream ( const char * mimetype, const char * window,
40           bool as_file = FALSE )
41       virtual void streamAsFile ( QNPStream *, const char * fname )
42       void * getJavaPeer () const
43       virtual void notifyURL ( const char * url, Reason r, void * notifyData
44           )
45       virtual bool printFullPage ()
46       virtual void print ( QPainter * )
47
48   Protected Members
49       QNPInstance ()
50

DESCRIPTION

52       This class is defined in the Qt Netscape Extension, which can be found
53       in the qt/extensions directory. It is not included in the main Qt API.
54
55       The QNPInstance class provides a QObject that is a web browser plugin.
56
57       Deriving from QNPInstance creates an object that represents a single
58       <EMBED> tag in an HTML document.
59
60       The QNPInstance is responsible for creating an appropriate QNPWidget
61       window if required (not all plugins have windows), and for interacting
62       with the input/output facilities intrinsic to plugins.
63
64       Note that there is absolutely no guarantee regarding the order in which
65       functions are called. Sometimes the browser will call newWindow()
66       first, at other times, newStreamCreated() will be called first
67       (assuming the <EMBED> tag has a SRC parameter).
68
69       None of Qt's GUI functionality may be used until after the first call
70       to newWindow(). This includes any use of QPaintDevice (i.e. QPixmap,
71       QWidget, and all subclasses), QApplication, anything related to
72       QPainter (QBrush, etc.), fonts, QMovie, QToolTip, etc. Useful classes
73       which specifically can be used are QImage, QFile, and QBuffer.
74
75       This restriction can easily be accommodated by structuring your plugin
76       so that the task of the QNPInstance is to gather data, while the task
77       of the QNPWidget is to provide a graphical interface to that data.
78
79   Member Type Documentation

QNPInstance::InstanceMode

81       This enum type provides Qt-style names for three #defines in npapi.h:
82
83       QNPInstance::Embed - corresponds to NP_EMBED
84
85       QNPInstance::Full - corresponds to NP_FULL
86
87       QNPInstance::Background - corresponds to NP_BACKGROUND
88

QNPInstance::Reason

90       QNPInstance::ReasonDone
91
92       QNPInstance::ReasonBreak
93
94       QNPInstance::ReasonError
95
96       QNPInstance::ReasonUnknown
97

QNPInstance::StreamMode

99       QNPInstance::Normal
100
101       QNPInstance::Seek
102
103       QNPInstance::AsFile
104
105       QNPInstance::AsFileOnly
106

MEMBER FUNCTION DOCUMENTATION

QNPInstance::QNPInstance () [protected]

109       Creates a QNPInstance.
110
111       Can only be called from within a derived class created within
112       QNPlugin::newInstance().
113

QNPInstance::~QNPInstance ()

115       Called when the plugin instance is about to be deleted.
116

const char * QNPInstance::arg ( const char * name ) const

118       Returns the value of the named arguments, or 0 if no argument called
119       name appears in the <EMBED> tag of this instance. If the argument
120       appears, but has no value assigned, the empty string is returned. In
121       summary:
122
123       <center>.nf
124
125       Tag
126       ────
127
128
129
130       </center>
131

int QNPInstance::argc () const

133       Returns the number of arguments to the instance. Note that you should
134       not normally rely on the ordering of arguments, and note that the SGML
135       specification does not permit multiple arguments with the same name.
136
137       See also arg() and argn().
138

const char * QNPInstance::argn ( int i ) const

140       Returns the name of the i-th argument.
141
142       See also argc() and argv().
143

const char * QNPInstance::argv ( int i ) const

145       Returns the value of the i-th argument.
146
147       \as argc(), arg()
148

void * QNPInstance::getJavaPeer () const

150       Returns the Java object associated with the plugin instance, an object
151       of the plugin's Java class, or 0 if the plug-in does not have a Java
152       class, Java is disabled, or an error occurred.
153
154       The return value is actually a jref we use void* so as to avoid
155       burdening plugins which do not require Java.
156
157       See also QNPlugin::getJavaClass() and QNPlugin::getJavaEnv().
158

void QNPInstance::getURL ( const char * url, const char * window = 0 )

160       Requests that the url be retrieved and sent to the named window. See
161       Netscape's JavaScript documentation for an explanation of window names.
162

void QNPInstance::getURLNotify ( const char * url, const char * window = 0,

164       void * data = 0 )
165       Requests that the given url be retrieved and sent to the named window.
166       See Netscape's JavaScript documentation for an explanation of window
167       names. Passes the arguments including data to NPN_GetURLNotify.
168
169       Netscape: NPN_GetURLNotify method
170

InstanceMode QNPInstance::mode () const

172       Returns the mode of the plugin.
173

QNPStream * QNPInstance::newStream ( const char * mimetype, const char *

175       window, bool as_file = FALSE )
176       This function is under development and is subject to change.
177
178       This function is not tested.
179
180       Requests the creation of a new data stream from the plugin. The MIME
181       type and window are passed in mimetype and window. as_file holds the
182       AsFileOnly flag. It is an interface to the NPN_NewStream function of
183       the Netscape Plugin API.
184

bool QNPInstance::newStreamCreated ( QNPStream *, StreamMode & smode )

186       [virtual]
187       This function is called when a new stream has been created. The
188       instance should return TRUE if it accepts the processing of the stream.
189       If the instance requires the stream as a file, it should set smode to
190       AsFileOnly, in which case the data will be delivered some time later to
191       the streamAsFile() function. Otherwise, the data will be delivered in
192       chunks to the write() function, which must consume at least as much
193       data as returned by the most recent call to writeReady().
194
195       Note that the AsFileOnly method is not supported by Netscape 2.0 and
196       MSIE 3.0.
197
198       The default implementation accepts any stream.
199

QNPWidget * QNPInstance::newWindow () [virtual]

201       Called at most once, at some time after the QNPInstance is created. If
202       the plugin requires a window, this function should return a derived
203       class of QNPWidget that provides the required interface.
204
205       Example: grapher/grapher.cpp.
206

void QNPInstance::notifyURL ( const char * url, Reason r, void * notifyData )

208       [virtual]
209       This function is under development and is subject to change.
210
211       This function is not tested.
212
213       Called whenever a url is notified after a call to NPN_GetURLNotify with
214       notifyData. The reason is given in r.
215
216       It is an encapsulation of the NPP_URLNotify function of the Netscape
217       Plugin API.
218
219       See also: Netscape: NPP_URLNotify method
220

void QNPInstance::postURL ( const char * url, const char * window, uint len,

222       const char * buf, bool file )
223       This function is under development and is subject to change.
224
225       This function is not tested.
226
227       It is an interface to the NPN_PostURL function of the Netscape Plugin
228       API.
229
230       Passes url, window, buf, len, and file to NPN_PostURL.
231

void QNPInstance::print ( QPainter * ) [virtual]

233       This function is under development and is subject to change.
234
235       This function is not tested.
236
237       Print the instance embedded in a page.
238
239       It is an encapsulation of the NPP_Print function of the Netscape Plugin
240       API.
241

bool QNPInstance::printFullPage () [virtual]

243       This function is under development and is subject to change.
244
245       This function is not tested.
246
247       It is an encapsulation of the NPP_Print function of the Netscape Plugin
248       API.
249

void QNPInstance::status ( const char * msg )

251       Sets the status message in the browser containing this instance to msg.
252

void QNPInstance::streamAsFile ( QNPStream *, const char * fname ) [virtual]

254       Called when a stream is delivered as a single file called fname rather
255       than as chunks. This may be simpler for a plugin to deal with, but
256       precludes any incremental behavior.
257
258       Note that the AsFileOnly method is not supported by Netscape 2.0 and
259       MSIE 3.0.
260
261       See also newStreamCreated() and newStream().
262

void QNPInstance::streamDestroyed ( QNPStream * ) [virtual]

264       Called when a stream is destroyed. At this point, the stream may be
265       complete() and okay(). If it is not okay(), then an error has occurred.
266       If it is okay(), but not complete(), then the user has cancelled the
267       transmission; do not give an error message in this case.
268

const char * QNPInstance::userAgent () const

270       Returns the user agent (browser name) containing this instance.
271

QNPWidget * QNPInstance::widget ()

273       Returns the plugin window created by newWindow(), if any.
274

int QNPInstance::write ( QNPStream *, int offset, int len, void * buffer )

276       [virtual]
277       Called when incoming data is available for processing by the instance.
278       The instance must consume at least the amount that it returned in the
279       most recent call to writeReady(), but it may consume up to the amount
280       given by len. buffer is the data available for consumption. The offset
281       argument is merely an informational value indicating the total amount
282       of data that has been consumed in prior calls.
283
284       This function should return the amount of data actually consumed.
285
286       Example: grapher/grapher.cpp.
287

int QNPInstance::writeReady ( QNPStream * ) [virtual]

289       Returns the minimum amount of data the instance is willing to receive
290       from the given stream.
291
292       The default returns a very large value.
293
294

SEE ALSO

296       http://doc.trolltech.com/qnpinstance.html
297       http://www.trolltech.com/faq/tech.html
298
300       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
301       license file included in the distribution for a complete license
302       statement.
303

AUTHOR

305       Generated automatically from the source code.
306

BUGS

308       If you find a bug in Qt, please report it as described in
309       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
310       help you. Thank you.
311
312       The definitive Qt documentation is provided in HTML format; it is
313       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
314       web browser. This man page is provided as a convenience for those users
315       who prefer man pages, although this format is not officially supported
316       by Trolltech.
317
318       If you find errors in this manual page, please report them to qt-
319       bugs@trolltech.com.  Please include the name of the manual page
320       (qnpinstance.3qt) and the Qt version (3.3.8).
321
322
323
324Trolltech AS                    2 February 2007               QNPInstance(3qt)
Impressum