pr_pushiolayer.rst (2864B)
1 PR_PushIOLayer 2 ============== 3 4 Adds a layer onto the stack. 5 6 7 Syntax 8 ------ 9 10 .. code:: 11 12 #include <prio.h> 13 14 PRStatus PR_PushIOLayer( 15 PRFileDesc *stack, 16 PRDescIdentity id, 17 PRFileDesc *layer); 18 19 20 Parameters 21 ~~~~~~~~~~ 22 23 The function has the following parameters: 24 25 ``stack`` 26 A pointer to a :ref:`PRFileDesc` object representing the stack. 27 ``id`` 28 A :ref:`PRDescIdentity` object for the layer on the stack above which 29 the new layer is to be added. 30 ``layer`` 31 A pointer to a :ref:`PRFileDesc` object representing the new layer to be 32 added to the stack. 33 34 35 Returns 36 ~~~~~~~ 37 38 The function returns one of the following values: 39 40 - If the layer is successfully pushed onto the stack, ``PR_SUCCESS``. 41 - If the layer is not successfully pushed onto the stack, 42 ``PR_FAILURE``. Use :ref:`PR_GetError` to get additional information 43 regarding the reason for the failure. 44 45 46 Description 47 ----------- 48 49 A file descriptor for a layer (possibly allocated using 50 :ref:`PR_CreateIOLayerStub`) may be pushed onto an existing stack of file 51 descriptors at any time. The new layer is inserted into the stack just 52 above the layer with the identity specified by ``id``. 53 54 Even if the ``id`` parameter indicates the topmost layer of the stack, 55 the value of the file descriptor describing the original stack will not 56 change. In other words, ``stack`` continues to point to the top of the 57 stack after the function returns. 58 59 Caution 60 ------- 61 62 Keeping the pointer to the stack even as layers are pushed onto the top 63 of the stack is accomplished by swapping the contents of the file 64 descriptor being pushed and the stack's current top layer file 65 descriptor. 66 67 The intent is that the pointer to the stack remain the stack's identity 68 even if someone (perhaps covertly) has pushed other layers. Some subtle 69 ramifications: 70 71 - The ownership of the storage pointed to by the caller's layer 72 argument is relinquished to the runtime. Accessing the object via the 73 pointer is not permitted while the runtime has ownership. The correct 74 mechanism to access the object is to get a pointer to it by calling 75 :ref:`PR_GetIdentitiesLayer`. 76 77 - The contents of the caller's object are swapped into another 78 container, including the reference to the object's destructor. If the 79 original container was allocated using a different mechanism than 80 used by the runtime, the default calling of the layer's destructor by 81 the runtime will fail :ref:`PR_CreateIOLayerStub` is provided to 82 allocate layer objects and template implementations). The destructor 83 will be called on all layers when the stack is closed (see 84 :ref:`PR_Close`). If the containers are allocated by some method other 85 than :ref:`PR_CreateIOLayerStub`, it may be required that the stack have 86 the layers popped off (in reverse order that they were pushed) before 87 calling :ref:`PR_Close`.