[vala-extra-vapis] Provides bindings for the FastCGI protocol.
- From: Evan Nemerson <evann src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [vala-extra-vapis] Provides bindings for the FastCGI protocol.
- Date: Thu, 19 Nov 2015 00:06:42 +0000 (UTC)
commit 6d026eea2a7f73367cdc6e6ceda7db6a9625876e
Author: Guillaume Poirier-Morency <guillaumepoiriermorency gmail com>
Date: Tue Jul 7 12:55:42 2015 -0400
Provides bindings for the FastCGI protocol.
The original code is available from apmasell/vapis GitHub repository
(https://github.com/apmasell/vapis).
Support for 'FCGX_FClose' and missing request struct attributes were
added.
Add licence declaration from the 'LICENCE.TERMS' file distributed with
the library.
fcgi.vapi | 546 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 546 insertions(+), 0 deletions(-)
---
diff --git a/fcgi.vapi b/fcgi.vapi
new file mode 100644
index 0000000..8c1343c
--- /dev/null
+++ b/fcgi.vapi
@@ -0,0 +1,546 @@
+/*
+ * This FastCGI application library source and object code (the
+ * "Software") and its documentation (the "Documentation") are
+ * copyrighted by Open Market, Inc ("Open Market"). The following terms
+ * apply to all files associated with the Software and Documentation
+ * unless explicitly disclaimed in individual files.
+ *
+ * Open Market permits you to use, copy, modify, distribute, and license
+ * this Software and the Documentation for any purpose, provided that
+ * existing copyright notices are retained in all copies and that this
+ * notice is included verbatim in any distributions. No written
+ * agreement, license, or royalty fee is required for any of the
+ * authorized uses. Modifications to this Software and Documentation may
+ * be copyrighted by their authors and need not follow the licensing
+ * terms described here. If modifications to this Software and
+ * Documentation have new licensing terms, the new terms must be clearly
+ * indicated on the first page of each file where they apply.
+ *
+ * OPEN MARKET MAKES NO EXPRESS OR IMPLIED WARRANTY WITH RESPECT TO THE
+ * SOFTWARE OR THE DOCUMENTATION, INCLUDING WITHOUT LIMITATION ANY
+ * WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN
+ * NO EVENT SHALL OPEN MARKET BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY
+ * DAMAGES ARISING FROM OR RELATING TO THIS SOFTWARE OR THE
+ * DOCUMENTATION, INCLUDING, WITHOUT LIMITATION, ANY INDIRECT, SPECIAL OR
+ * CONSEQUENTIAL DAMAGES OR SIMILAR DAMAGES, INCLUDING LOST PROFITS OR
+ * LOST DATA, EVEN IF OPEN MARKET HAS BEEN ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGES. THE SOFTWARE AND DOCUMENTATION ARE PROVIDED "AS IS".
+ * OPEN MARKET HAS NO LIABILITY IN CONTRACT, TORT, NEGLIGENCE OR
+ * OTHERWISE ARISING OUT OF THIS SOFTWARE OR THE DOCUMENTATION.
+ */
+
+/**
+ * FastCGI server interface library
+ *
+ * This library makes it easy to be a server for FastCGI programs so that a web
+ * server, like Apache, nginx, or lighthttpd can proxy for this application.
+ *
+ * There are three interfaces: a CGI-esque interface available through
+ * { link stdin} and friends, a single-threaded interface available via
+ * { link accept} and a multi-threaded interface available via { link request}.
+ */
+[CCode (cheader_filename = "fcgiapp.h")]
+namespace FastCGI {
+
+ /**
+ * FastCGI's abstraction over a file I/O
+ */
+ [CCode (cname = "FCGI_FILE", cheader_filename = "fcgi_stdio.h", free_function = "FCGI_pclose",
has_type_id = false)]
+ public class FileStream {
+ public int descriptor {
+ [CCode (cname = "FCGI_fileno")]
+ get;
+ }
+ public GLib.FileStream file_stream {
+ [CCode (cname = "FCGI_ToFILE")]
+ get;
+ }
+ public Stream stream {
+ [CCode (cname = "FCGI_ToFcgiStream")]
+ get;
+ }
+
+ [CCode (cname = "FCGI_fopen")]
+ public static FileStream? open (string path, string mode);
+ [CCode (cname = "FCGI_fdopen")]
+ public static FileStream? fdopen (int fildes, string mode);
+ [CCode (cname = "FCGI_tmpfile")]
+ public static FileStream? tmpfile ();
+ [CCode (cname = "FCGI_popen")]
+ public static FileStream? popen (string cmd, string type);
+ [ReturnsModifiedPointer]
+ [CCode (cname = "FCGI_freopen", instance_pos = -1)]
+ public static FileStream? reopen (string path, string mode);
+ [CCode (cname = "FCGI_clearerr")]
+ public void clear_error ();
+ [CCode (cname = "FCGI_feof")]
+ public bool eof ();
+ [CCode (cname = "FCGI_fflush")]
+ public int flush ();
+ [CCode (cname = "FCGI_fgetc")]
+ public int getc ();
+ [CCode (cname = "FCGI_fgets", instance_pos = -1)]
+ public unowned string? gets (char[] s);
+ [CCode (cname = "FCGI_ferror")]
+ public int get_error ();
+ [CCode (cname = "FCGI_fprintf")]
+ [PrintfFormat ()]
+ public void printf (string format, ...);
+ [CCode (cname = "FCGI_fputc", instance_pos = -1)]
+ public void putc (char c);
+ [CCode (cname = "FCGI_fputs", instance_pos = -1)]
+ public void puts (string s);
+ [CCode (cname = "FCGI_fread", instance_pos = -1)]
+ public size_t read ([CCode (array_length_pos = 2.1)] uint8[] buf, size_t size = 1);
+ [CCode (cname = "FCGI_rewind")]
+ public void rewind ();
+ [CCode (cname = "FCGI_fseek")]
+ public int seek (long offset, GLib.FileSeek whence);
+ [CCode (cname = "FCGI_ftell")]
+ public int tell ();
+ [CCode (cname = "FCGI_ungetc", instance_pos = -1)]
+ public int ungetc (int c);
+ [CCode (cname = "FCGI_vfprintf")]
+ public void vprintf (string format, va_list args);
+ [CCode (cname = "FCGI_fwrite", instance_pos = -1)]
+ public size_t write ([CCode (array_length_pos = 2.1)] uint8[] buf, size_t size = 1);
+ }
+ /**
+ * The state of a FastCGI stream.
+ *
+ * Streams are modeled after the { link GLib.FileStream}. (We wouldn't need
+ * our own if platform vendors provided a standard way to subclass theirs.)
+ * The state of a stream is private and should only be accessed by the
+ * procedures defined below.
+ */
+ [CCode (cname = "FCGX_Stream", free_function = "FCGX_FClose", has_type_id = false)]
+ [Compact]
+ public class Stream {
+ [CCode (cname = "isReader")]
+ public bool is_reader;
+ [CCode (cname = "isClosed")]
+ public bool is_closed;
+
+ /**
+ * Create a stream (used by cgi-fcgi).
+ *
+ * This shouldn't be needed by a FastCGI application.
+ */
+ [CCode (cname = "FCGX_CreateWriter")]
+ public static Stream create_writer (int socket, int request_id, int bufflen, int streamType);
+
+ /**
+ * Clear the stream error code and end-of-file indication.
+ */
+ [CCode (cname = "FCGX_ClearError")]
+ public void clear_error ();
+
+ /**
+ * Flushes any buffered output.
+ *
+ * Server-push is a legitimate application of this method. Otherwise,
+ * this method is not very useful, since { link accept} does it
+ * implicitly. Calling it in non-push applications results in extra
+ * writes and therefore reduces performance.
+ */
+ [CCode (cname = "FCGX_FFlush")]
+ public bool flush ();
+
+ /**
+ * Closes the stream. For writers, flushes any buffered output.
+ *
+ * Close is not a very useful operation since FCGX_Accept does it
+ * implicitly. Closing the out stream before the err stream results in
+ * an extra write if there's nothing in the err stream, and therefore
+ * reduces performance.
+ *
+ * @return EOF (-1) if an error occurred.
+ */
+ [CCode (cname = "FCGX_FClose")]
+ public int close ();
+
+ /**
+ * Return the stream error code.
+ * @return 0 means no error, > 0 is an errno(2) error, < 0 is an FastCGI error.
+ */
+ [CCode (cname = "FCGX_GetError")]
+ public int get_error ();
+
+ /**
+ * Reads a byte from the input stream and returns it.
+ *
+ * @return The byte, or { link GLib.FileStream.EOF} if the end of input has been reached.
+ */
+ [CCode (cname = "FCGX_GetChar")]
+ public int getc ();
+
+ [CCode (cname = "FCGX_GetLine", instance_pos = 1.2)]
+ public unowned string? gets (uint8[] buffer);
+
+ /**
+ * Returns true if end-of-file has been detected while reading from
+ * stream.
+ *
+ * Note that this may return false, yet an immediately following
+ * { link getc} may return EOF. This function, like the standard C stdio
+ * function { link GLib.FileStream.eof}, does not provide the ability to
+ * peek ahead.
+ */
+ [CCode (cname = "FCGX_HasSeenEOF")]
+ public bool has_seen_eof ();
+
+ /**
+ * Performs printf-style output formatting and writes the results to the
+ * output stream.
+ *
+ * @return Number of bytes written for normal return, or { link GLib.FileStream.EOF}
+ * if an error occurred.
+ */
+ [CCode (cname = "FCGX_FPrintF")]
+ [PrintfFormat]
+ public int printf (string format, ...);
+
+ /**
+ * Writes the buffer into the output stream.
+ *
+ * Performs no interpretation of the output bytes.
+ *
+ * @return Number of bytes written for normal return, or { link GLib.FileStream.EOF}
+ * if an error occurred.
+ */
+ [CCode (cname = "FCGX_PutStr", instance_pos = 1.3)]
+ public int put_str (uint8[] buffer);
+
+ /**
+ * Writes a byte to the output stream.
+ *
+ * @return The byte, or { link GLib.FileStream.EOF} if an error occurred.
+ */
+ [CCode (cname = "FCGX_PutChar", instance_pos = 1.2)]
+ public int putc (int c);
+
+ /**
+ * Writes a string to the output stream.
+ * @return Number of bytes written for normal return, or { link GLib.FileStream.EOF}
+ * if an error occurred.
+ */
+ [CCode (cname = "FCGX_PutS", instance_pos = -1)]
+ public int puts (string str);
+
+ /**
+ * Reads up to consecutive bytes from the input stream
+ * into the character array.
+ *
+ * Performs no interpretation of the input bytes.
+ * @return Number of bytes read. If result is smaller than the buffer size,
+ * end of input has been reached.
+ */
+ [CCode (cname = "FCGX_GetStr", instance_pos = 1.2)]
+ public int read (uint8[] buffer);
+
+ /**
+ * Sets the exit status for stream's request.
+ *
+ * The exit status is the status code the request would have exited
+ * with, had the request been run as a CGI program. You can call this
+ * several times during a request; the last call before the request ends
+ * determines the value.
+ */
+ [CCode (cname = "FCGX_SetExitStatus", instance_pos = 1.2)]
+ public void set_exit_status (int status);
+
+ /**
+ * Repositions an input stream to the start of FCGI_DATA.
+ *
+ * If the preconditions are not met sets the stream error code to
+ * { link CALL_SEQ_ERROR}.
+ *
+ * @return 0 for a normal return, < 0 for error
+ */
+ [CCode (cname = "FCGX_StartFilterData")]
+ public int start_filter ();
+
+ /**
+ * Pushes back the character onto the input stream.
+ *
+ * One character of pushback is guaranteed once a character
+ * has been read. No pushback is possible for EOF.
+ *
+ * @return c if the pushback succeeded, { link GLib.FileStream.EOF} if not.
+ */
+ [CCode (cname = "FCGX_UnGetChar", instance_pos = 1.2)]
+ public int ungetc (int c);
+
+ [CCode (cname = "FCGX_VFPrintF")]
+ public int vprintf (string format, va_list arg);
+ }
+
+ /**
+ * CGI parameters
+ */
+ [CCode (cname = "FCGX_ParamArray", has_type_id = false)]
+ [SimpleType]
+ public struct parameters {
+ [CCode (cname = "FCGX_GetParam", instance_pos = -1)]
+ public unowned string? get (string name);
+ [CCode (array_null_terminated = true, array_length = false)]
+ public unowned string[] get_all () {
+ return (string[]) this;
+ }
+ }
+
+ /**
+ * State associated with a request.
+ *
+ * This is the API for multi-threaded code. Code should be structured like
+ * this:
+ *
+ * {{{
+ * int descriptor;
+ * Mutex mutex;
+ * void handler() {
+ * FastCGI.request request;
+ * assert(FastCGI.request.init(out request, descriptor) == 0);
+ * while (true) {
+ * mutex.lock () ;
+ * var fail = request.accept() < 0;
+ * mutex.unlock();
+ * if (fail)
+ * break;
+ * // Process request
+ * request.finish();
+ * }
+ * request.close(false);
+ * }
+ * void main() {
+ * mutex = new Mutex();
+ * assert(FastCGI.init() == 0);
+ * stderr.printf("I:open_socket path=\"%s\" backlog=%d\n", socket_path, backlog);
+ * descriptor = FastCGI.open_socket(socket_path, backlog);
+ * assert(descriptor != -1);
+ * try {
+ * while (thread_count > 1) {
+ * Thread.create<void>(handler, false);
+ * thread_count--;
+ * }
+ * handler();
+ * } catch(ThreadError e) {
+ * // Handle error
+ * }
+ * }
+ * }}}
+ *
+ * It is important that only one thread at a time attempt to call
+ * { link accept}, hence the mutex. The request can be read from the client
+ * using { link environment} and the response can be written to the client
+ * using { link out}.
+ */
+ [CCode (cname = "FCGX_Request", has_type_id = false, destroy_function = "")]
+ public struct request {
+ [CCode (cname = "envp")]
+ public parameters environment;
+ public Stream err;
+ public Stream @in;
+ public Stream @out;
+ [CCode (cname = "requestId")]
+ public int request_id;
+ public int role;
+
+ /* Don't use anything below here */
+ [CCode (cname = "ipcFd")]
+ public int ipc_fd;
+ [CCode (cname = "isBeginProcessed")]
+ public bool is_begin_processed;
+ [CCode (cname = "keepConnection")]
+ public bool keep_connection;
+ public int app_status;
+ [CCode (cname = "nWriters")]
+ public int number_of_writers;
+ public int flags;
+ [CCode (cname = "listen_sock")]
+ public int listen_socket;
+
+ /**
+ * Accept a new request
+ *
+ * Thread-safe.
+ *
+ * Finishes the request accepted by (and frees any storage allocated by)
+ * the previous call. Creates input, output, and error streams and
+ * assigns them to in, out, and err respectively. Creates a parameters
+ * data structure.
+ *
+ * DO NOT retain pointers to the envp or any strings contained in it,
+ * since these will be freed by the next call or a call to { link finish}.
+ *
+ * @return 0 for successful call, -1 for error.
+ */
+ [CCode (cname = "FCGX_Accept_r")]
+ public int accept ();
+
+ /**
+ * Close this stream.
+ * @param close_descriptor Close the underlying file descriptor.
+ */
+ [CCode (cname = "FCGX_Free")]
+ [DestroysInstance]
+ public void close (bool close_descriptor = true);
+
+ /**
+ * Finish the request
+ *
+ * Thread-safe.
+ *
+ * Finishes the request accepted by (and frees any storage allocated by)
+ * the previous call to { link accept}.
+ *
+ * DO NOT retain pointers to the envp array or any strings contained in
+ * it, since these will be freed.
+ */
+ [CCode (cname = "FCGX_Finish_r")]
+ public void finish ();
+
+ /**
+ * Initialize a request.
+ *
+ * @param sock is a file descriptor returned by { link open_socket} or 0 (default).
+ *
+ * @return 0 upon success.
+ */
+ [CCode (cname = "FCGX_InitRequest")]
+ public static int init (out request request, int sock = 0, RequestFlags flags =
RequestFlags.NONE);
+
+ /**
+ * Get a named parameter from the environment.
+ */
+ public unowned string? @get (string name) {
+ return environment[name];
+ }
+ }
+
+ [CCode (cname = "int", cprefix = "FCGI_", has_type_id = false)]
+ [Flags]
+ public enum RequestFlags {
+ [CCode (cname = "0")]
+ NONE,
+ /**
+ * Do not restart upon being interrupted.
+ */
+ FAIL_ACCEPT_ON_INTR
+ }
+
+ /**
+ * Accept a new request
+ *
+ * NOT thread-safe.
+ *
+ * Finishes the request accepted by (and frees any storage allocated by) the
+ * previous call. Creates input, output, and error streams and assigns them
+ * to in, out, and err respectively. Creates a parameters data structure
+ * and assigns it to envp.
+ *
+ * DO NOT retain pointers to the envp array or any strings contained in it,
+ * since these will be freed by the next call or a call to { link finish}.
+ *
+ * Code is generally of this form:
+ *
+ * {{{
+ * Stream @in;
+ * Stream @out;
+ * Stream @err;
+ * unowned parameters envp;
+ * while(accept(out @in, out @out, out @err, out envp) == 0) {
+ * // Process request, writing output to @out.
+ * finish();
+ * }
+ * }}}
+ *
+ * @return 0 for successful call, -1 for error.
+ */
+ [CCode (cname = "FCGX_Accept")]
+ public int accept (out Stream @in, out Stream @out, out Stream err, out unowned parameters envp);
+
+ /**
+ * Finish the current request
+ *
+ * NOT thread-safe.
+ *
+ * Finishes the request accepted by (and frees any storage allocated by) the
+ * previous call to { link accept}.
+ *
+ * DO NOT retain pointers to the { link parameters} or any strings contained
+ * in it, since these will be freed.
+ *
+ * @see accept
+ */
+ [CCode (cname = "FCGX_Finish")]
+ public void finish ();
+
+ /**
+ * Initialize the FCGX library.
+ *
+ * Call in multi-threaded apps.
+ * @return 0 upon success.
+ */
+ [CCode (cname = "FCGX_Init")]
+ public int init ();
+
+ /**
+ * Is this process a CGI process rather than a FastCGI process.
+ */
+ [CCode (cname = "FCGX_IsCGI")]
+ public bool is_cgi ();
+
+ /**
+ * Create a FastCGI listen socket.
+ *
+ * @param path is the Unix domain socket (named pipe for WinNT), or a colon
+ * followed by a port number. (e.g. "/tmp/fastcgi/mysocket", ":5000")
+ * @param backlog is the listen queue depth used in the listen() call.
+ * @return the socket's file descriptor or -1 on error.
+ */
+ [CCode (cname = "FCGX_OpenSocket")]
+ public int open_socket (string path, int backlog);
+
+ /**
+ * Prevent the lib from accepting any new requests.
+ *
+ * Signal handler safe.
+ */
+ [CCode (cname = "FCGX_ShutdownPending")]
+ public void shutdown_pending ();
+
+ /**
+ * Standard error abstraction using FastCGI.
+ *
+ * This should be used if you are not using the multi-threaded { link accept}
+ * or { link request}-based API.
+ */
+ [CCode (cname = "FCGI_stderr", cheader_filename = "fcgi_stdio.h")]
+ public static FileStream stderr;
+ /**
+ * Standard input abstraction using FastCGI.
+ *
+ * This should be used if you are not using the multi-threaded { link accept}
+ * or { link request}-based API.
+ */
+ [CCode (cname = "FCGI_stdin", cheader_filename = "fcgi_stdio.h")]
+ public static FileStream stdin;
+ /**
+ * Standard output abstraction using FastCGI.
+ *
+ * This should be used if you are not using the multi-threaded { link accept}
+ * or { link request}-based API.
+ */
+ [CCode (cname = "FCGI_stdout", cheader_filename = "fcgi_stdio.h")]
+ public static FileStream stdout;
+
+ [CCode (cname = "FCGX_CALL_SEQ_ERROR")]
+ public const int CALL_SEQ_ERROR;
+ [CCode (cname = "FCGX_PARAMS_ERROR")]
+ public const int PARAMS_ERROR;
+ [CCode (cname = "FCGX_PROTOCOL_ERROR")]
+ public const int PROTOCOL_ERROR;
+ [CCode (cname = "FCGX_UNSUPPORTED_VERSION")]
+ public const int UNSUPPORTED_VERSION;
+}
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
