.NODE

Streams API

The streams layer is easily the largest piece of PHP's core API. To help navigate through the sheer volume of method calls, this section of the appendix will attempt to break them down into functional groupings covering creation, access, manipulation, and destruction.

Stream Creation and Destruction

php_stream *php_stream_alloc(php_stream_ops *ops, void *abstract,
 const char *persistent_id, const char *mode);

Allocates a PHP Stream instance associated with the identified stream ops. This method is typically used by stream or wrapper implementations; refer to Chapter 15.

Argument

Purpose

ops

Structure containing a list of callback operations for performing read, write, flush, close, and other operations.

abstract

Attaches an arbitrary data structure to the stream instance, typically referring to the underlying data resource.

persistent_id

Unique identifier for this stream resource used for retrieving persistent stream instances.

mode

fopen mode to associate with this stream instance (such as r, w, a, r+, and so on).

int php_stream_from_persistent_id(const char *persistent_id,
 php_stream **stream TSRMLS_DC);

Recovers a stream instance based on its persistent ID (as provided to php_stream_alloc().

int php_stream_free(php_stream *stream, int close_options);
int php_stream_close(php_stream *stream);
int php_stream_pclose(php_stream *stream);

Closes a stream and free the resources associated with it. close_options can be any combination of the following flags. php_stream_close() calls php_stream_free() with close_options set to PHP_STREAM_FREE_CLOSE, while php_stream_pclose() calls it with PHP_STREAM_FREE_CLOSE_PERSISTENT.

close_options Flags

Description

PHP_STREAM_FREE_CALL_DTOR

Call the stream's ops->close() method

PHP_STREAM_FREE_RELEASE_STREAM

Free memory allocated to store the stream instance

PHP_STREAM_FREE_PRESERVE_HANDLE

Passed to ops->close() to instruct it not to close the underlying handle

PHP_STREAM_FREE_RSRC_DTOR

Used internally by the streams layer to avoid recursion when destroying the stream's associated resource

PHP_STREAM_FREE_PERSISTENT

Explicitly close an otherwise persistent stream instance

PHP_STREAM_FREE_CLOSE

Combination of PHP_STREAM_FREE_CALL_DTOR and PHP_STREAM_FREE_RELEASE_STREAM

PHP_STREAM_FREE_CLOSE_CASTED

Combination of PHP_STREAM_FREE_CLOSE and PHP_STREAM_FREE_PRESERVE_HANDLE

PHP_STREAM_FREE_CLOSE_PERSISTENT

Combination of PHP_STREAM_FREE_CLOSE and PHP_STREAM_FREE_PERSISTENT

php_stream_wrapper *php_stream_locate_url_wrapper(const char *path,
 char **path_for_open, int options TSRMLS_DC);

Retrieves the currently registered wrapper struct associated with a given URI. Typically path_for_open will simply be populated with the value of path; however, when filebased URIs are given, the leading file:// scheme identifier will be automatically stripped so that calls to the underlying open() syscall will function normally.

Argument

Purpose

path

Full URI of resource to be mapped to its wrapper structure.

path_for_open

Populated with (possibly) modified version of path to use in actual open call.

options

Bitmask flag containing zero or more of the following options: IGNORE_URL, STREAM_LOCATE_WRAPPERS_ONLY, and REPORT_ERRORS. Refer to Chapter 14 for explanations of these flags.

php_stream *php_stream_open_wrapper(char *path, char *mode,
 int options, char **opened_path);
php_stream *php_stream_open_wrapper_ex(char *path, char *mode,
 int options, char **opened_path,
 php_stream_context *context);
FILE *php_stream_open_wrapper_as_file(char *path, char *mode,
 int options, char **opened_path);

Creates a stream instance or stdio file pointer from the given path. The php_stream_open_wrapper() variant functions identically to the extended version with a value of NULL passed for context. If php_stream_open_wrapper_as_file() is called for a protocol that does not support casting to FILE*, the streams layer will raise an error, close the intermediate stream, and return NULL.

Argument

Purpose

path

URI pointing to location of resource to be opened.

mode

Access mode to apply to file being opened (such as r, w+, a, and so on).

options

Zero or more of the stream open options described in Chapter 14.

opened_path

Populated with the actual location of the opened resource. Due to symlinks and redirects, this will commonly be different from the actual path requested.

context

Stream context to be used while opening or accessing the stream.

 

Stream I/O

size_t php_stream_read(php_stream *stream, char *buf, size_t maxlen);
char *php_stream_get_record(php_stream *stream, size_t maxlen,
 size_t *returned_len, char *delim,
 size_t delim_len TSRMLS_DC);
char *php_stream_get_line(php_stream *stream, char *buf, size_t maxlen,
 size_t *returned_len);
char *php_stream_gets(php_stream *stream, char *buf, size_t maxlen);
int php_stream_getc(php_stream *stream);

Reads data from a stream instance. php_stream_read() reads raw bytes with no regard to their content and only attempts one read call to the underlying transport. This means that, depending on the underlying implementation's semantics, fewer than maxlen bytes can be returned even if more data is currently available. Conversely, the three line-oriented data retrieval operations (get_record, get_line, and gets) perform a greedy read, buffering up as much of the stream's data as necessary to either locate an end of line sequence, or fill the provided buffer to maxlen bytes. php_stream_getc() will read a single byte from the stream.

Argument

Purpose

stream

Stream instance to read from.

buf

Buffer to store results to. For methods that return char*, if buf is passed as NULL, a buffer of appropriate size will be emalloc'd to the appropriate size.

maxlen

Maximum number of bytes to read from the stream.

delim

"End of line" delimiter. Sequence at which to stop reading from the stream. Does not require a terminating NULL byte.

delim_len

Length of delimiter string, not including any optional terminating NULL characters.

returned_len

Length of string returned by methods otherwise returning a char* buffer.

size_t php_stream_write(php_stream *stream, const char *buf, size_t count)
size_t php_stream_write_string(php_stream *stream, const char *buf);
int php_stream_puts(php_stream *stream, char *buf);
size_t php_stream_printf(php_stream *stream TSRMLS_DC, const char *fmt, ...);
int php_stream_putc(php_stream *stream, int c);

Writes data to a stream instance. php_stream_puts() differs from php_stream_write() by appending an additional newline character after writing the contents of buf. The putc and puts varieties return 1 on success or 0 on failure while the remaining versions return the number of bytes actually written on the streamwhich may be fewer that the number of bytes requested to write.

Argument

Purpose

stream

Stream to write data to

buf

Buffer containing data to be written to stream

count

Number of bytes of data contained in buf

c

Single character to write to stream

fmt

sprintf() style format specifier

...

Variable argument list corresponding to fmt specifier

int php_stream_eof(php_stream *stream);

Returns a nonzero value if the stream's file pointer has reached the end of file.

int php_stream_flush(php_stream *stream, int closing);

Instructs the underlying stream implementation to flush any internally buffered data to the target resource.

size_t php_stream_copy_to_stream(php_stream *src,
 php_stream *dest, size_t maxlen);

Reads remaining contentup to maxlen bytesfrom src stream and write it out to dest stream.

size_t php_stream_copy_to_mem(php_stream *src, char **buffer,
 size_t maxlen, int persistent);

Reads remaining contentup to maxlen bytesfrom src stream and place it into a newly allocated buffer. If persistent is nonzero, permanent memory allocators will be used; otherwise, non-persistent memory will be allocated for buffer.

size_t php_stream_passthru(php_stream * src);

Reads remaining content from src stream and output it to the browser, command line, or other appropriate target.

char *php_stream_mmap_range(php_stream *stream, size_t offset,
 size_t length, php_stream_mmap_operation_t mode,
 size_t *mapped_len);
int php_stream_mmap_unmap(php_stream *stream TSRMLS_DC);
int php_stream_mmap_supported(php_stream *stream);
int php_stream_mmap_possible(php_stream *stream);

Maps or unmaps a portion of a stream's contents to memory. Note that PHP imposes an artificial limit of 2MB on memory mapping operations. The functions returning integers yield zero for failure or to indicate a negative response, or nonzero otherwise. php_stream_mmap_range() returns a pointer to the mem-mapped range on success, or NULL on failure.

Argument

Purpose

stream

Stream to map

offset

Beginning offset in the stream's contents from which to map

length

Number of bytes to map; use PHP_STREAM_COPY_ALL to map all of the remaining data (however much is available)

mode

Set to PHP_STREAM_MMAP_MAP_RANGE; other values are used internally by the streams layer

mapped_len

Populated with the actual number of bytes mapped to the pointer returned by this method

 

Stream Manipulation

int php_stream_seek(php_stream *stream, off_t offset, int whence);
int php_stream_rewind(php_stream *stream);
off_t php_stream_tell(php_stream *stream);

Moves the file pointer within a seekable stream (seek) or report its current position (tell). php_stream_rewind() is provided as a convenience macro mapping to php_stream_seek(stream,0, SEEK_SET);.

Argument

Purpose

stream

Stream to seek or report the location on

offset

Position to seek to relative to the whence

whence

One of SEEK_SET (relative to beginning of stream), SEEK_CUR (relative to current position), or SEEK_END (relative to end of file)

int php_stream_stat(php_stream *stream, php_stream_statbuf *ssb);
int php_stream_stat_path(char *path, int flags, php_stream_statbuf *ssb,
 php_stream_context *context);

Reports fstat() or stat() style information from an open stream or URI path respectively.

Argument

Purpose

stream

Active stream instance to retrieve fstat() information from.

path

URL to a local or remote file resource to retrieve stat() data from.

flags

If set to PHP_STREAM_URL_STAT_LINK, only the immediate resource pointed to by path will be inspected. If this flag is not set, symlinks will be followed to a real resource.

ssb

Stat buffer to populate filestat information into.

context

Stream context to apply when attempting to locate the local or remote resource.

int php_stream_set_option(php_stream *stream, int option,
 int value, void *ptrparam);
int php_stream_truncate_set_size(php_stream *stream, size_t newsize);

Performs an ioctl() style operation on PHP stream. php_stream_truncate_set_size() is a convenience wrapper for php_stream_set_option(stream, PHP_STREAM_OPTION_TRUNCATE_API, PHP_STREAM_TRUNCATE_SET_SIZE, &newsize);, which instructs the underlying stream implementation to change the size of its associated file resource.

The full list of options is a topic unto itself and is beyond the scope of this book. Refer to the source code of stream implementations such as main/streams/plain_wrapper.c and main/streams/xp_socket.c to see the implementation side of these controls.

int php_stream_can_cast(php_stream *stream, int castas);
int php_stream_cast(php_stream *stream, int castas, void **ret, int show_err);

Exposes a stream as a more fundamental system type such as a file descriptor or filestream object. castas must be passed as exactly one of the type flags: PHP_STREAM_AS_STDIO, PHP_STREAM_AS_FD, PHP_STREAM_AS_SOCKETD, or PHP_STREAM_AS_FD_FOR_SELECT optionally combined via bitwise OR with PHP_STREAM_CAST_RELEASE, which will invalidate future uses of the owning stream object. To test if a stream can be cast without actually performing the operation, call php_stream_can_cast() instead. Both methods return SUCCESS or FAILURE.

Argument

Purpose

stream

Stream to be cast.

castas

Type of resource to cast the stream to.

ret

Pointer to a local variable to store the casted stream to.

show_err

Set to a nonzero value to raise php_errors()s if the cast encounters errors.

int php_stream_make_seekable(php_stream *origstream,
 php_stream **newstream, int flags);

If origstream is already seekable, and flags does not contain PHP_STREAM_FORCE_CONVERSION, newstream will simply be set to origstream and this method will return PHP_STREAM_UNCHANGED. Otherwise, a new temporary stream will be created and the remaining contents of origstream will be copied to newstream. Note that any content already read from origstream will not become available as a result of calling this method. If the method succeeds, origstream will be closed and the call will return PHP_STREAM_RELEASED. Should it fail, it will return PHP_STREAM_FAILURE to indicate the temporary stream could not be created, or PHP_STREAM_CRITICAL to indicate that the contents of origstream could not be copied to newstream. Note that a copy failure might result in some or all data from origstream being lost. In addition to PHP_STREAM_FORCE_CONVERSION, flags can also be combined with PHP_STREAM_PREFER_STDIO, which will create a STDIO tempfile rather than a temporary file descriptor.

Directory Access

int php_stream_mkdir(char *path, int mode, int options,
 php_stream_context *context);
int php_stream_rmdir(char *path, int options,
 php_stream_context *context);

Creates a new directory or remove one. The criteria and method for creating or removing a directory is wrapper-specific; however, all wrappers implementing the mkdir() method are expected to respect the PHP_STREAM_MKDIR_RECURSIVE option. Note that there are no options flags actually defined for php_stream_rmdir(). This argument exists purely for forward compatibility.

Argument

Purpose

path

URI describing directory to be created or removed.

mode

POSIX access mode to apply to the newly created directory.

options

Bitmask flag argument withcurrentlyone option: PHP_STREAM_MKDIR_RECURSIVE, which applies only to the mkdir() variant of these methods. When used, any nonexisting parent directories required by the given path will be implicitly created as well.

context

Stream context to apply to wrapper execution.

php_stream *php_stream_opendir(char *path, int options,
 php_stream_context *context);
php_stream_dirent *php_stream_readdir(php_stream *stream,
 php_stream_dirent *ent);
int php_stream_rewinddir(php_stream *stream);
int php_stream_close(php_stream *stream);

Opens, iteratively reads entries from, and closes a directory resource. Directory entries are read in block increments of equal size. The contents of a directory entry can be accessed via ent->d_name.

Argument

Purpose

path

URI pointing to directory to be examined.

options

Optional parameters to pass during stream creation. Refer to Chapter 14 for a listing of these options and what they do.

context

Stream context to apply while opening this directory resource.

stream

Active directory stream instance to read from, rewind, or close.

ent

Directory entry buffer that will be populated with the next directory entry name.

int php_stream_scandir(char *path, char **namelist[],
 php_stream_context *context,
 int (*compare) (const char **a, const char **b));
int php_stream_dirent_alphasort(const char **a, const char **b);
int php_stream_dirent_alphasortr(const char **a, const char **b);

php_stream_scandir() will read all entries within a given directory into a vector of char* strings. If a compare functionsuch as one of the alphasort methods shownis provided, the entries will be sorted after being read. Space for the namelist vector and each individual entry will be automatically allocated by the php_stream_scandir() method using nonpersistent storage and must be manually freed after use. For example, a namelist containing 10 entries will have 11 distinct allocationsone for the vector itself, and another for the individual strings within that vector.

Argument

Purpose

path

URI pointing to the directory to scan for entries.

namelist

Passed as a pointer to local char** storage. This will be modified by reference by the scandir method.

context

Stream context to use while scanning the directory.

compare

Comparison function to use for sorting. Can be either of the alphasort methods given previously, or any callback that accepts two elements as its input and returns -1, 0, or 1 to indicate less-than, equal, or greater-than, respectively.

 

Internal/Userspace Conversion

int php_file_le_stream(void);
int php_file_le_pstream(void);
int php_file_le_stream_filter(void);
int php_le_stream_context(void);

Returns list entry type IDs for standard streams, persistent streams, filters, and contexts. These values correspond to the values assigned by zend_register_list_destructors() and are used by helper macros such as php_stream_from_zval().

void php_stream_to_zval(php_stream *stream, zval *zstream);
void php_stream_from_zval(php_stream *stream, zval *zstream);
void php_stream_from_zval_no_verify(php_stream *stream, zval *zstream);

These helper macros encode an allocated stream to a userspace zval, or decode it back again. Note that these are macros and not regular functions, therefore the stream variable passed to the php_stream_from_zval*(); functions is modified in place. The php_stream_from_zval() macro, unique among the rest, will produce php_error() warnings if the zstream value passed is not a valid PHP Stream resource. Refer back to Chapter 9, "The Resource Data Type," for more information on registering and retrieving resource values.

Contexts

php_stream_context *php_stream_context_alloc(void);
void php_stream_context_free(php_stream_context *context);

Allocates or frees a stream context. Refer to Chapter 16, "Diverting the Stream," for a more complete explanation of the usage of stream contexts.

int php_stream_context_set_option(php_stream_context *context,
 const char *wrappername, const char *optionname,
 zval *optionvalue);
int php_stream_context_get_option(php_stream_context *context,
 const char *wrappername, const char *optionname,
 zval ***optionvalue);

Sets or retrieves a context option. Context options are stored in a two-dimensional array of zval* values. The name of the base wrapper defines the first dimension, whereas a wrapper-specific option name defines the second. Wrappers that serve double duty, such as http and https, typically use only one wrapper name (in this case, http) for storing their context options.

Argument

Purpose

context

Context container to set or retrieve options on.

wrappername

Name of the base wrapper for which this option applies.

optionname

Wrapper-specific option name to get or set.

optionvalue

Depending on the specific method called, either a zval* value to store into the context option, or pointer to a local zval** variable to fetch a previously stored value back into. Note that when storing a value it is explicitly separated (copied) by the streams layer, detaching it from the calling scope's ownership.

php_stream_context *php_stream_context_set(php_stream *stream,
php_stream_context *context);

Associates a context with an already active stream instance. Because most context options take effect when the stream is opened, this action will typically have much less impact than specifying the context to the stream creation method.

Notifiers

php_stream_notifier *php_stream_notification_alloc(void);
void php_stream_notification_free(php_stream_notifier *notifier);
void php_stream_notification_notify(php_stream_context *context,
 int notifycode, int severity, char *xmsg,
 int xcode, size_t bytes_sofar, size_t bytes_max,
 void * ptr TSRMLS_DC);

Refer to Chapter 16 for details on the use of these methods.

Filters

php_stream_filter *php_stream_filter_create(const char *filtername,
 zval *filterparams, int persistent TSRMLS_DC);

Instantiates a filter using the filter-specific parameters provided. When instantiating a filter object to be placed on a persistent stream, the persistent flag must be set. This can usually be accomplished by using the php_stream_is_persistent() method.

Argument

Purpose

filtername

Name of the filter to instantiate.

filterparams

Optional zval* containing filter-specific parameters. Refer to documentation for the filter being instantiated for the types and values accepted.

persistent

Binary flag indicating whether the filter will be placed on a persistent stream.

php_stream_filter *php_stream_filter_alloc(php_stream_filter_ops *fops,
 void *abstract, int persistent);
void php_stream_filter_free(php_stream_filter *filter TSRMLS_DC);

Allocates or frees a filter structure. php_stream_filter_alloc() is typically used by filter implementations during instantiation. The free method will automatically call the filter's dtor method to clean up any internal resources.

Argument

Purpose

fops

Filter ops structure containing callbacks to use with this filter instance.

abstract

Arbitrary data pointer to associate with the filter instance.

persistent

Flag indicating whether the filter will be placed on a persistent stream.

void php_stream_filter_prepend(php_stream_filter_chain *chain,
 php_stream_filter *filter);
void php_stream_filter_append(php_stream_filter_chain *chain,
 php_stream_filter *filter);
int php_stream_filter_flush(php_stream_filter *filter, int finish);
php_stream_filter *php_stream_filter_remove(php_stream_filter *filter,
 int call_free TSRMLS_DC);

Adds a filter to the beginning or end of a stream's filter stack, flushes its internal buffers, or removes a filter from an active stream. Typically a filter will be flushed prior to removing it so that internally buffered data can be passed to later filters or the read-buffer/write-op as appropriate.

Argument

Purpose

chain

Filter chain to add the named filter to. Typically one of stream->readfilters or stream->writefilters.

filter

Filter instance to add, flush, or remove.

finish

When set to a nonzero value, the filter is instructed to flush as much data from its internal buffers as possible. Otherwise, the filter can choose to only flush the current block of data while retaining some for the next cycle.

call_free

Automatically call php_stream_filter_free() after removing it from its stream's filter chain.

int php_stream_filter_register_factory(const char *filterpattern,
 php_stream_filter_factory *factory TSRMLS_DC);
int php_stream_filter_unregister_factory(
 const char *filterpattern TSRMLS_DC);
int php_stream_filter_register_factory_volatile(const char *filterpattern,
 php_stream_filter_factory *factory TSRMLS_DC);
int php_stream_filter_unregister_factory_volatile(
 const char *filterpattern TSRMLS_DC);

Registers or unregisters a stream filter. The volatile variant of these methods allows wrappers to be overridden for the life of a single request only, whereas the nonvolatile versions handle permanent registrations and unregistrations. As with wrappers, volatile filters should be registered and unregistered during request phasesACTIVATE, RUNTIME, DEACTIVATEonly, permanent filters, likewise, should only be registered and unregistered during the STARTUP and SHUTDOWN phases.

Buckets

php_stream_bucket *php_stream_bucket_new(php_stream *stream,
 char *buf, size_t buflen, int own_buf,
 int buf_persistent TSRMLS_DC);

Instantiates a bucket object to place on a filter brigade. Refer to Chapter 16 for information on using buckets with custom filter implementations.

Argument

Purpose

stream

Reference to the stream this bucket will ultimately be associated with.

buf

Data buffer to assign to this bucket.

buflen

Length of buf in bytes.

own_buf

Set to a nonzero value if buf can be safely altered or freed by another filter or the streams layer. If this and buf_persistent are set to 0, and the target stream is not persistent, buf will be automatically copied so that the bucket owns a modifiable buffer.

buf_persistent

Set to a nonzero value if the passed buf data will remain available and unchanged for the life of the current request.

void php_stream_bucket_delref(php_stream_bucket *bucket TSRMLS_DC);

Reduce the internal refcount of the named bucket. In practice, buckets rarely exceed a refcount of one, so this call usually destroys the bucket completely.

int php_stream_bucket_split(php_stream_bucket *in, php_stream_bucket **left,
 php_stream_bucket **right, size_t length TSRMLS_DC);

Divides the contents of a bucket into two new buckets. The in bucket is consumed and delref'd in the process of splitting with length bytes of buffer data placed in the new bucket populated into left, and any remaining data placed in the new bucket populated into right.

void php_stream_bucket_prepend(php_stream_bucket_brigade *brigade,
 php_stream_bucket *bucket TSRMLS_DC);
void php_stream_bucket_append(php_stream_bucket_brigade *brigade,
 php_stream_bucket *bucket TSRMLS_DC);
void php_stream_bucket_unlink(php_stream_bucket *bucket TSRMLS_DC);

Adds or removes a bucket to/from a bucket brigade.

php_stream_bucket *php_stream_bucket_make_writeable(php_stream_bucket *bucket
 TSRMLS_DC);

Ensures that the data contained in a bucket can be safely modified by the calling scope. If necessary, the bucket will duplicate the contents of its internal buffer in order to make it writeable.

Plainfiles and Standard I/O

php_stream *php_stream_fopen(const char *filename,
 const char *mode, char **opened_path);
php_stream *php_stream_fopen_with_path(char *filename, char *mode,
 char *include_path, char **opened_path);

Local filesystem variant of the php_stream_open_wrapper() method. This version will not dispatch to any stream wrappers other than the plainfiles wrapper, and does not provide a means to specify a context parameter. Neither versions of this method use the php.ini include_path value; however, the _with_path() variant does allow an include_path set to be specified.

php_stream *php_stream_fopen_from_file(FILE *file, const char *mode);
php_stream *php_stream_fopen_from_fd(int fd, const char *mode,
 const char *persistent_id);
php_stream *php_stream_sock_open_from_socket(php_socket_t socket,
 const char *persistent_id);
php_stream *php_stream_fopen_from_pipe(FILE *file, const char *mode);

Casts an already opened file descriptor or stdio file pointer to a PHP stream.

Argument

Purpose

file / fd

Existing file descriptor or stdio file pointer to wrap in a PHP stream

mode

fopen mode to associate with the stream

persistent_id

Persistent ID to assign to the stream

php_stream *php_stream_temp_create(int mode, size_t max_memory_usage);
php_stream *php_stream_temp_open(int mode, size_t max_memory_usage,
 char *buf, size_t length);

Creates a temporary stream suitable for reading and writing. When the stream is closed, any contents within the stream as well as secondary resources are discarded. Initially, temporary data is stored in RAM; however, if the size of the stored data grows beyond max_memory_usage, the contents of the memory stream will be written to a temporary file on disk and all further interim storage will take place there.

Argument

Purpose

mode

One of: TEMP_STREAM_DEFAULT, TEMP_STREAM_READONLY, or TEMP_STREAM_TAKE_BUFFER.

max_memory_usage

Maximum amount of memory to allocate for temporary data storage. Once this limit is exceeded, a temp file will be used as the storage medium instead.

buf

Initial buffer to create the temporary stream with.

length

Size of buf in bytes.

char *expand_filepath(const char *filepath, char *real_path TSRMLS_DC);

Resolves symlinks and parent references in the provided filepath to its real target. This method provides a thread-safe replacement to the standard realpath() method.

Transports

php_stream *php_stream_xport_create(const char *name, long namelen,
 int options, int flags, const char *persistent_id,
 struct timeval *timeout, php_stream_context *context,
 char **error_string, int *error_code);

Instantiates a socket transport stream. Depending on the passed flags, this can be a client or server socket, which may or may not immediately connect or start listening.

Argument

Purpose

name

Transport URI. If no protocol specifier is given, tcp:// is assumed for backward compatibility with the userspace fsockopen() command.

namelen

Length of a name argument, not including its trailing NULL.

options

The same options parameter used with php_stream_open_wrapper().

flags

Bitwise OR combination of the STREAM_XPORT flags.

persistent_id

Persistent ID associated with this transport. If available, and the socket is still live, the existing stream will be reused rather than opening a new one.

timeout

Maximum time to block while performing a synchronous connection.

context

Optional stream context.

error_string

Populated with a descriptive error if one occurs.

error_code

Populated with a numeric error code if one occurs.

The flags parameter can consist of either STREAM_XPORT_CLIENT or STREAM_XPORT_SERVER. A client transport can optionally specify either STREAM_XPORT_CONNECT or STREAM_XPORT_CONNECT_ASYNC. Server transports can specify STREAM_XPORT_BIND and STREAM_XPORT_LISTEN.

Flag

Meaning

STREAM_XPORT_CLIENT

Create a client-style transport.

STREAM_XPORT_SERVER

Create a server-style transport.

STREAM_XPORT_CONNECT

Immediately connect to the specified resource using a blocking (synchronous) call.

STREAM_XPORT_BIND

Bind to the specified local resource.

STREAM_XPORT_LISTEN

Listen for inbound connections on the transport socket. Typically requires the inclusion of STREAM_XPORT_BIND. By default, a backlog of five connections will be queued.

STREAM_XPORT_CONNECT_ASYNC

Begin connecting to the specified resource asynchronously.

int php_stream_xport_connect(php_stream *stream, const char *name, long namelen,
 int asynchronous, struct timeval *timeout,
 char **error_text, int *error_code TSRMLS_DC);

Connects a transport stream to the specified resource.

Argument

Purpose

stream

Transport stream to connect to the specified resource

name

Transport protocolspecific resource specified to connect to

namelen

Length of resource specifier

asynchronous

Set to a nonzero value to connect asynchronously

timeout

Maximum length of time to wait for a successful connection

error_text

Populated with descriptive error message on failure

error_code

Populated with numeric error code

int php_stream_xport_bind(php_stream *stream, const char *name, long namelen,
 char **error_text TSRMLS_DC);

Binds the established stream to a local resource. This can be used for binding server sockets or for source-binding clients prior to connection.

Argument

Purpose

stream

Transport stream to bind to a local resource

name

String describing the local resource to bind to

namelen

Length of name excluding its trailing NULL byte

error_test

Populated with textual error message if the bind was unsuccessful

int php_stream_xport_listen(php_stream *stream, int backlog,
 char **error_text TSRMLS_DC);

Begins listening on the previously bound transport socket.

Argument

Meaning

stream

Transport stream to bind to a local resource

backlog

Number of unaccepted connections to queue before rejecting additional connection attempts

error_test

Populated with textual error message if the bind was unsuccessful

int php_stream_xport_accept(php_stream *stream, php_stream **client,
 char **textaddr, int *textaddrlen,
 void **addr, socklen_t *addrlen,
 struct timeval *time out, char **error_text TSRMLS_DC);

Accepts a queued connection on a transport socket previously instructed to listen. If no connections are currently queued, this method will block for the period specified by time_out.

Argument

Purpose

stream

Server transport stream previously bound and instructed to listen. Connections will be accepted from this transport's backlog.

client

Populated with newly created transport stream using accepted connection.

textaddr

Populated with textual representation of addr.

textaddrlen

Populated with length of textaddr.

addr

Populated with transport-specific address structure.

addrlen

Populated with length of transport-specific address structure.

time_out

Maximum length of time to wait for an inbound connection. NULL to wait indefinitely.

error_text

Populated with textual error message if one occurs.

int php_stream_xport_get_name(php_stream *stream, int want_peer,
 char **textaddr, int *textaddrlen,
 void **addr, socklen_t *addrlen TSRMLS_DC);

Probes the local or remote transport end-point (socket) name.

Argument

Purpose

stream

Connected transport stream

want_peer

Set to nonzero to retrieve the remote end-point's information

textaddr

Populated with textual representation of address information

textaddrlen

Populated with length of textaddr

addr

Populated with transport protocolspecific address information

addrlen

Populated with length of addr

int php_stream_xport_sendto(php_stream *stream, const char *buf, size_t buflen,
 long flags, void *addr, socklen_t addrlen TSRMLS_DC);
int php_stream_xport_recvfrom(php_stream *stream, char *buf, size_t buflen,
 long flags, void **addr, socklen_t *addrlen,
 char **textaddr, int *textaddrlen TSRMLS_DC);

Connectionless send and receive methods.

Argument

Meaning

stream

Transport stream to use for sending or receiving.

buf

Data to be sent or buffer to populate received data into.

buflen

Length of data to send or length of buffer to receive data into.

flags

Can optionally be set to STREAM_OOB to send or receive out-of-band data. When receiving, can also be set to or combined with STREAM_PEEK to inspect data without consuming it.

addr

When sending: protocol-specific address record to send to. When receiving: populated with protocol-specific source address record.

addrlen

Length of addr in bytes.

textaddr

Populated with textual representation of source address.

textaddrlen

Populated with length of textaddr.

int php_stream_xport_crypto_setup(php_stream *stream,
 php_stream_xport_crypt_method_t crypto_method,
 php_stream *session_stream TSRMLS_DC);

int php_stream_xport_crypto_enable(php_stream *stream, int activate TSRMLS_DC);

Sets up and activates/deactivates encryption on the specified transport stream. In practice only the SSL/TLS crypto methods are implemented and these are only typically used with the TCP transport.

Argument

Purpose

stream

Transport stream to setup cryptography on.

crypto_method

One of: STREAM_CRYPTO_METHOD_SSLv2_CLIENT,

STREAM_CRYPTO_METHOD_SSLv3_CLIENT,

STREAM_CRYPTO_METHOD_SSLv23_CLIENT,

STREAM_CRYPTO_METHOD_TLS_CLIENT,

STREAM_CRYPTO_METHOD_SSLv2_SERVER,

STREAM_CRYPTO_METHOD_SSLv3_SERVER,

STREAM_CRYPTO_METHOD_SSLv23_SERVER, or

STREAM_CRYPTO_METHOD_TLS_SERVER.

session_stream

If provided, the new crypto setup will inherit session parameters from a previously crypto-enabled transport stream.

activate

When set to a nonzero value, the crypto-layer will be enabled; when set to zero, it will be turned off.

int php_stream_xport_register(char *protocol,
 php_stream_transport_factory factory TSRMLS_DC);
typedef php_stream *(*php_stream_transport_factory)(
 const char *proto, long protolen,
 char *resourcename, long resourcenamelen,
 const char *persistent_id, int options, int flags,
 struct timeval *timeout, php_stream_context *context
 STREAMS_DC TSRMLS_DC);
int php_stream_xport_unregister(char *protocol TSRMLS_DC);

Registers or unregisters a stream transport factory. Transport factory methods follow the same pattern as stream protocol wrapper opener functions. Refer to Chapter 15 for an overview of stream creation methods.

Argument

Purpose

protocol

Name of protocol to register or unregister.

factory

Factory method called when a transport of the specified protocol is instantiated.

proto

Name of transport protocol being instantiated.

protolen

Length of proto.

resourcename

Protocol-specific URI indicating resource to connect to.

resourcenamelen

Length of resourcename.

persistent_id

Persistent ID associated with the transport stream being instantiated.

options

Option values as passed to php_stream_xport_create().

flags

Flag values as passed to php_stream_xport_create().

timeout

Default timeout value for transport.

context

Optional context parameter to be associated with the stream.

HashTable *php_stream_xport_get_hash(void);

Returns a pointer to the internal transport registry hash.

int php_network_parse_network_address_with_port(const char *addr, long addrlen,
 struct sockaddr *sa, socklen_t *sl TSRMLS_DC);

Parses an inet family transport URI into its component parts. If the host portion of the URI is hostname it will be automatically resolved to its IP address. The appropriate address family, address, and port data are loaded into the sa sockaddr structure and its final size is populated into sl.

Miscellaneous

int php_register_url_stream_wrapper(char *protocol,
 php_stream_wrapper *wrapper TSRMLS_DC);
int php_unregister_url_stream_wrapper(char *protocol TSRMLS_DC);
int php_register_url_stream_wrapper_volatile(char *protocol,
 php_stream_wrapper *wrapper TSRMLS_DC);
int php_unregister_url_stream_wrapper_volatile(char *protocol TSRMLS_DC);

Registers or unregisters a stream protocol wrapper. The volatile variant of these methods allows wrappers to be overridden for the life of a single request only, whereas the nonvolatile versions handle permanent registrations and unregistrations. Needless to say, volatile wrappers should be registered and unregistered during request phasesACTIVATE, RUNTIME, DEACTIVATEonly, permanent wrappers, by contrast, should only be registered and unregistered during the STARTUP and SHUTDOWN phases. Refer to Chapter 15 for more information.

void php_stream_wrapper_log_error(php_stream_wrapper *wrapper,
 int options TSRMLS_DC, const char *format, ...);

Reports a stream error via the wrapper subsystem. This method is typically called from wrapper operations such as stream_open. Refer to Chapter 15 for more information on reporting wrapper errors.

Argument

Purpose

wrapper

Reference to the currently active wrapper.

options

Typically passed through from the parameter stack. If the REPORT_ERRORS flag is set, the error message will be dispatched via PHP's normal error handling mechanism with php_error(). If it's not set, the message will be appended to the current wrappers error log.

format

sprintf() style format specifier.

...

Variable argument list corresponding to format.

HashTable *php_stream_get_url_stream_wrappers_hash(void);
HashTable *php_stream_get_url_stream_wrappers_hash_global(void);
HashTable *php_get_stream_filters_hash(void);
HashTable *php_get_stream_filters_hash_global(void);

Returns a reference to the internal registry of wrappers and filters. The _global() variants of these methods contain the persistent wrapper and filter definitions while the non _global() versions return this list as it has been modified by volatile registrations.

int php_stream_is(php_stream *stream, php_stream_ops *ops);

Returns nonzero if stream implements the named stream ops.

int php_stream_is_persistent(php_stream *stream);

Returns a nonzero value if the named stream instance is meant to be persistent between requests.

int php_is_url(char *path);

Returns a nonzero value if the named path specifies a network-based resource.

char *php_strip_url_passwd(char *path);

Strips the password from a standard formatted URL. Note that this method modifies the provided path in place; therefore, the value provided must be owned by the calling process and be modifiable.


The PHP Life Cycle

Variables from the Inside Out

Memory Management

Setting Up a Build Environment

Your First Extension

Returning Values

Accepting Parameters

Working with Arrays and HashTables

The Resource Data Type

PHP4 Objects

PHP5 Objects

Startup, Shutdown, and a Few Points in Between

INI Settings

Accessing Streams

Implementing Streams

Diverting the Stream

Configuration and Linking

Extension Generators

Setting Up a Host Environment

Advanced Embedding

Appendix A. A Zend API Reference

Appendix B. PHPAPI

Appendix C. Extending and Embedding Cookbook

Appendix D. Additional Resources

show all menu





Extending and Embedding PHP
Extending and Embedding PHP
ISBN: 067232704X
EAN: 2147483647
Year: 2007
Pages: 175
Authors: Sara Golemon
Similar book on Amazon

Flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net