82 lines
2.7 KiB
Markdown
82 lines
2.7 KiB
Markdown
# 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`.
|