NPN_PostURL

« Gecko Plugin API Reference « Plug-in Side Plug-in API

Summary

Posts data to a URL.

Syntax

#include <npapi.h>
NPError NPN_PostURL(NPP instance, const char *url,
                    const char *target, uint32 len,
                    const char *buf, NPBool file);

Parameters

The function has the following parameters:

instance

Pointer to the current plug-in instance.

url

URL of the request, specified by the plug-in.

target

Display target, specified by the plug-in. If null, pass the new stream back to the current plug-in instance regardless of MIME type. For values, see NPN_GetURL.

len

Length of the buffer buf.

buf

Path to local temporary file or data buffer that contains the data to post. Temporary file is deleted after use. Data in buffer cannot be posted for a protocol that requires a header.

file

A boolean value that specifies whether to post a file. Values:

true: Post the file whose path is specified in buf, then delete the file.
false: Post the raw data in buf.

Returns

If successful, the function returns NPERR_NO_ERROR.
If unsuccessful, the plug-in is not loaded and the function returns an error code. For possible values, see Error Codes.

Description

NPN_PostURL works similarly to NPN_GetURL, but in reverse.

NPN_GetURL reads data from the URL and either displays it in the target window or delivers it to the plug-in.
NPN_PostURL writes data from a file or buffer to the URL and either displays the server's response in the target window or delivers it to the plug-in. If the target parameter is null, the new stream is passed to the plug-in regardless of MIME type.

When you use NPN_PostURL to send data to the server, you can handle the response in several different ways by specifying different target parameters.

If target is null, the server response is sent back to the plug-in. You can get the data and save it in a file or use it in a program.
If you specify _current, _self, or _top, the response data is written to the same plug-in window and the plug-in is unloaded.
If you specify _new or _blank, the response data is written to a new browser window. You can also write the response data to a frame by specifying the frame name as the target parameter.

For HTTP URLs only, the browser resolves this method as the HTTP server method POST, which transmits data to the server.

The data to post can be contained either in a local temporary file or a new memory buffer.

To post to a temporary file, set the flag file to true, the buffer buf to the path name string for a file, and len to the length of the path string. The file-type URL prefix "file://" is optional.

MS Windows and OS X

If a file is posted with any protocol other than FTP, the file must be text with Unix-style line breaks ('\n' separators only).

To post data from a memory buffer, set the flag file to false, the buffer buf to the data to post, and len to the length of buffer.

Possible URL types include HTTP (similar to an HTML form submission), mail (sending mail), news (posting a news article), and FTP (upload a file). Plug-ins can use this function to post form data to CGI scripts using HTTP or upload files to a remote server using FTP.

You cannot use NPN_PostURL to specify headers (even a blank line) in a memory buffer. To do this, use NPN_PostURLNotify.

For protocols in which the headers must be distinguished from the body, such as HTTP, the buffer or file should contain the headers, followed by a blank line, then the body. If no custom headers are required, simply add a blank line ('\n') to the beginning of the file or buffer.

NPN_PostURL is typically asynchronous: it returns immediately and only later handles the request. For this reason, you may find it useful to call NPN_PostURLNotify instead; this function notifies your plug-in upon successful or unsuccessful completion of the request.