index.rst (4808B)
1 .. _mozilla_projects_nss_reference_nspr_functions: 2 3 NSPR functions 4 ============== 5 6 .. container:: 7 8 `NSPR <https://www.mozilla.org/projects/nspr/>`__ is a platform abstraction library that provides 9 a cross-platform API to common OS services. NSS uses NSPR internally as the porting layer. 10 However, a small number of NSPR functions are required for using the certificate verification and 11 SSL functions in NSS. These NSPR functions are listed in this section. 12 13 .. _nspr_initialization_and_shutdown: 14 15 `NSPR initialization and shutdown <#nspr_initialization_and_shutdown>`__ 16 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 17 18 .. container:: 19 20 NSPR is automatically initialized by the first NSPR function called by the application. Call 21 ```PR_Cleanup`` </en-US/PR_Cleanup>`__ to shut down NSPR and clean up its resources.\ ` 22 </en-US/PR_Init>`__ 23 24 - `PR_Cleanup </en-US/PR_Cleanup>`__ 25 26 .. _error_reporting: 27 28 `Error reporting <#error_reporting>`__ 29 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 30 31 .. container:: 32 33 NSS uses NSPR's thread-specific error code to report errors. Call 34 ```PR_GetError`` </en-US/PR_GetError>`__ to get the error code of the last failed NSS or NSPR 35 function. Call ```PR_SetError`` </en-US/PR_SetError>`__ to set the error code, which can be 36 retrieved with ``PR_GetError`` later. 37 38 The NSS functions ``PORT_GetError`` and ``PORT_SetError`` are simply wrappers of ``PR_GetError`` 39 and ``PR_SetError``. 40 41 - `PR_GetError </en-US/PR_GetError>`__ 42 - `PR_SetError </en-US/PR_SetError>`__ 43 44 .. _calendar_time: 45 46 `Calendar time <#calendar_time>`__ 47 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 48 49 .. container:: 50 51 NSS certificate verification functions take a ``PRTime`` parameter that specifies the time 52 instant at which the validity of the certificate should verified. The NSPR function 53 ```PR_Now`` </en-US/PR_Now>`__ returns the current time in ``PRTime``. 54 55 - `PR_Now </en-US/PR_Now>`__ 56 57 .. _interval_time: 58 59 `Interval time <#interval_time>`__ 60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 61 62 .. container:: 63 64 The NSPR socket I/O functions ```PR_Recv`` </en-US/PR_Recv>`__ and 65 ```PR_Send`` </en-US/PR_Send>`__ (used by the NSS SSL functions) take a ``PRIntervalTime`` 66 timeout parameter. ``PRIntervalTime`` has an abstract, platform-dependent time unit. Call 67 ```PR_SecondsToInterval`` </en-US/PR_SecondsToInterval>`__ or ``PR_MillisecondsToInterval`` to 68 convert a time interval in seconds or milliseconds to ``PRIntervalTime``. 69 70 - `PR_SecondsToInterval </en-US/PR_SecondsToInterval>`__ 71 - `PR_MillisecondsToInterval </en-US/PR_MillisecondsToInterval>`__ 72 73 .. _nspr_io_layering: 74 75 `NSPR I/O layering <#nspr_io_layering>`__ 76 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 77 78 .. container:: 79 80 NSPR file descriptors can be layered, corresponding to the layers in the network stack. The SSL 81 library in NSS implements the SSL protocol as an NSPR I/O layer, which sits on top of another 82 NSPR I/O layer that represents TCP. 83 84 You can implement an NSPR I/O layer that wraps your own TCP socket code. The following NSPR 85 functions allow you to create your own NSPR I/O layer and manipulate it. 86 87 - `PR_GetUniqueIdentity </en-US/PR_GetUniqueIdentity>`__ 88 - `PR_CreateIOLayerStub </en-US/PR_CreateIOLayerStub>`__ 89 - `PR_GetDefaultIOMethods </en-US/PR_GetDefaultIOMethods>`__ 90 - `PR_GetIdentitiesLayer </en-US/PR_GetIdentitiesLayer>`__ 91 - `PR_GetLayersIdentity </en-US/PR_GetLayersIdentity>`__ 92 - `PR_PushIOLayer </en-US/PR_PushIOLayer>`__ 93 - `PR_PopIOLayer </en-US/PR_PopIOLayer>`__ 94 95 .. _wrapping_a_native_file_descriptor: 96 97 `Wrapping a native file descriptor <#wrapping_a_native_file_descriptor>`__ 98 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 99 100 .. container:: 101 102 If your current TCP socket code uses the standard BSD socket API, a lighter-weight method than 103 creating your own NSPR I/O layer is to simply import a native file descriptor into NSPR. This 104 method is convenient and works for most applications. 105 106 - `PR_ImportTCPSocket </en-US/PR_ImportTCPSocket>`__ 107 108 .. _socket_io_functions: 109 110 `Socket I/O functions <#socket_io_functions>`__ 111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 112 113 .. container:: 114 115 As mentioned above, the SSL library in NSS implements the SSL protocol as an NSPR I/O layer. 116 Users call NSPR socket I/O functions to read from, write to, and shut down an SSL connection, and 117 to close an NSPR file descriptor. 118 119 - `PR_Read </en-US/PR_Read>`__ 120 - `PR_Write </en-US/PR_Write>`__ 121 - `PR_Recv </en-US/PR_Recv>`__ 122 - `PR_Send </en-US/PR_Send>`__ 123 - `PR_GetSocketOption </en-US/PR_GetSocketOption>`__ 124 - `PR_SetSocketOption </en-US/PR_SetSocketOption>`__ 125 - `PR_Shutdown </en-US/PR_Shutdown>`__ 126 - `PR_Close </en-US/PR_Close>`__