mirror of
https://github.com/logos-storage/nim-libplum.git
synced 2026-06-07 17:49:25 +00:00
131 lines
3.6 KiB
Markdown
131 lines
3.6 KiB
Markdown
# API Reference
|
|
|
|
## Types
|
|
|
|
```nim
|
|
type PlumProtocol* = enum
|
|
TCP
|
|
UDP
|
|
```
|
|
|
|
```nim
|
|
type PlumState* = enum
|
|
Destroyed
|
|
Pending
|
|
Success
|
|
Failure
|
|
Destroying
|
|
```
|
|
|
|
```nim
|
|
type MappingProtocol* = enum
|
|
Unknown ## not yet determined (mapping pending)
|
|
PCP ## Port Control Protocol
|
|
NatPmp ## NAT Port Mapping Protocol
|
|
UPnP ## UPnP-IGD
|
|
Direct ## no mapping needed, local address is already public
|
|
```
|
|
|
|
```nim
|
|
type PlumMapping* = object
|
|
protocol*: PlumProtocol ## IP protocol (TCP/UDP)
|
|
mappingProtocol*: MappingProtocol ## NAT traversal protocol used
|
|
internalPort*: uint16
|
|
externalPort*: uint16
|
|
externalHost*: string
|
|
```
|
|
|
|
```nim
|
|
type MappingResult* = object
|
|
id*: cint
|
|
mapping*: PlumMapping
|
|
```
|
|
|
|
```nim
|
|
type PlumStateCallback* =
|
|
proc(state: PlumState, mapping: PlumMapping) {.cdecl, raises: [], gcsafe.}
|
|
```
|
|
|
|
## Procedures
|
|
|
|
### init
|
|
|
|
```nim
|
|
proc init*(
|
|
logLevel: plum_log_level_t = PLUM_LOG_LEVEL_NONE,
|
|
discoverTimeout: int = 0,
|
|
mappingTimeout: int = 0,
|
|
recheckPeriod: int = 0
|
|
): Result[void, string]
|
|
```
|
|
|
|
Initializes the library and starts the internal thread. Must be called before any other proc.
|
|
|
|
- `logLevel`: verbosity of internal logs, from `PLUM_LOG_LEVEL_VERBOSE` to `PLUM_LOG_LEVEL_NONE` (default: none); import `libplum/libplum` to access these constants
|
|
- `discoverTimeout`: how long to probe for a NAT device, in ms (default: 10000)
|
|
- `mappingTimeout`: how long to wait for a mapping response, in ms (default: 10000)
|
|
- `recheckPeriod`: interval between periodic mapping rechecks, in ms (default: 300000)
|
|
|
|
### cleanup
|
|
|
|
```nim
|
|
proc cleanup*(): Result[void, string]
|
|
```
|
|
|
|
Stops the internal thread and releases all resources. Returns an error if called more than once or before `init`.
|
|
|
|
### createMapping
|
|
|
|
```nim
|
|
proc createMapping*(
|
|
protocol: PlumProtocol,
|
|
internalPort: uint16,
|
|
externalPort: uint16 = 0,
|
|
timeout: Duration = seconds(30),
|
|
onStateChange: PlumStateCallback = nil
|
|
): Future[Result[MappingResult, string]]
|
|
```
|
|
|
|
Requests a port mapping from the NAT device. Tries PCP, then NAT-PMP, then UPnP-IGD in order.
|
|
|
|
- `protocol`: `TCP` or `UDP`
|
|
- `internalPort`: the local port to map
|
|
- `externalPort`: preferred external port, or 0 to let the router choose
|
|
- `timeout`: how long to wait for the mapping to be established (default: 30s)
|
|
- `onStateChange`: optional callback invoked when the mapping state changes after the initial result
|
|
|
|
Returns a `MappingResult` containing the mapping `id` (needed for `destroyMapping`) and the `PlumMapping` with the external address, port, and `mappingProtocol` indicating which protocol was used (`PCP`, `NatPmp`, or `UPnP`).
|
|
|
|
Returns an error if no NAT device is found, the mapping fails, or the timeout expires.
|
|
|
|
> **Warning:** `onStateChange` runs on libplum's internal C thread, not the
|
|
> chronos event loop. Do not call chronos APIs or touch non-thread-safe state
|
|
> from it; restrict it to thread-safe operations (e.g. `Atomic`, a channel).
|
|
|
|
### destroyMapping
|
|
|
|
```nim
|
|
proc destroyMapping*(id: cint)
|
|
```
|
|
|
|
Removes a mapping. Must be called exactly once after a successful `createMapping`,
|
|
otherwise the mapping's internal handle is leaked for the lifetime of the process.
|
|
Calling it again, or with an unknown `id`, is a safe no-op. `cleanup` also releases
|
|
any mappings still active.
|
|
|
|
### hasMapping
|
|
|
|
```nim
|
|
proc hasMapping*(id: cint): bool
|
|
```
|
|
|
|
Returns true if the mapping exists and has not been destroyed yet.
|
|
|
|
### getLocalAddress
|
|
|
|
```nim
|
|
proc getLocalAddress*(): Result[string, string]
|
|
```
|
|
|
|
Returns the local IP address as seen from the network interface. Useful to check whether the machine already has a public IP (in which case no NAT mapping is needed).
|