diff options
Diffstat (limited to '')
-rw-r--r-- | docs/nspr/reference/pr_pushiolayer.rst | 87 |
1 files changed, 87 insertions, 0 deletions
diff --git a/docs/nspr/reference/pr_pushiolayer.rst b/docs/nspr/reference/pr_pushiolayer.rst new file mode 100644 index 0000000000..067370108f --- /dev/null +++ b/docs/nspr/reference/pr_pushiolayer.rst @@ -0,0 +1,87 @@ +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`. |