87 lines
2.8 KiB
ReStructuredText
87 lines
2.8 KiB
ReStructuredText
PR_PushIOLayer
|
|
==============
|
|
|
|
Adds a layer onto the stack.
|
|
|
|
|
|
Syntax
|
|
------
|
|
|
|
.. code::
|
|
|
|
#include <prio.h>
|
|
|
|
PRStatus PR_PushIOLayer(
|
|
PRFileDesc *stack,
|
|
PRDescIdentity id,
|
|
PRFileDesc *layer);
|
|
|
|
|
|
Parameters
|
|
~~~~~~~~~~
|
|
|
|
The function has the following parameters:
|
|
|
|
``stack``
|
|
A pointer to a :ref:`PRFileDesc` object representing the stack.
|
|
``id``
|
|
A :ref:`PRDescIdentity` object for the layer on the stack above which
|
|
the new layer is to be added.
|
|
``layer``
|
|
A pointer to a :ref:`PRFileDesc` object representing the new layer to be
|
|
added to the stack.
|
|
|
|
|
|
Returns
|
|
~~~~~~~
|
|
|
|
The function returns one of the following values:
|
|
|
|
- If the layer is successfully pushed onto the stack, ``PR_SUCCESS``.
|
|
- If the layer is not successfully pushed onto the stack,
|
|
``PR_FAILURE``. Use :ref:`PR_GetError` to get additional information
|
|
regarding the reason for the failure.
|
|
|
|
|
|
Description
|
|
-----------
|
|
|
|
A file descriptor for a layer (possibly allocated using
|
|
:ref:`PR_CreateIOLayerStub`) may be pushed onto an existing stack of file
|
|
descriptors at any time. The new layer is inserted into the stack just
|
|
above the layer with the identity specified by ``id``.
|
|
|
|
Even if the ``id`` parameter indicates the topmost layer of the stack,
|
|
the value of the file descriptor describing the original stack will not
|
|
change. In other words, ``stack`` continues to point to the top of the
|
|
stack after the function returns.
|
|
|
|
Caution
|
|
-------
|
|
|
|
Keeping the pointer to the stack even as layers are pushed onto the top
|
|
of the stack is accomplished by swapping the contents of the file
|
|
descriptor being pushed and the stack's current top layer file
|
|
descriptor.
|
|
|
|
The intent is that the pointer to the stack remain the stack's identity
|
|
even if someone (perhaps covertly) has pushed other layers. Some subtle
|
|
ramifications:
|
|
|
|
- The ownership of the storage pointed to by the caller's layer
|
|
argument is relinquished to the runtime. Accessing the object via the
|
|
pointer is not permitted while the runtime has ownership. The correct
|
|
mechanism to access the object is to get a pointer to it by calling
|
|
:ref:`PR_GetIdentitiesLayer`.
|
|
|
|
- The contents of the caller's object are swapped into another
|
|
container, including the reference to the object's destructor. If the
|
|
original container was allocated using a different mechanism than
|
|
used by the runtime, the default calling of the layer's destructor by
|
|
the runtime will fail :ref:`PR_CreateIOLayerStub` is provided to
|
|
allocate layer objects and template implementations). The destructor
|
|
will be called on all layers when the stack is closed (see
|
|
:ref:`PR_Close`). If the containers are allocated by some method other
|
|
than :ref:`PR_CreateIOLayerStub`, it may be required that the stack have
|
|
the layers popped off (in reverse order that they were pushed) before
|
|
calling :ref:`PR_Close`.
|