[#PCPRequestPortMap]
= PCPRequestPortMap
:mrdocs:

Try to open a port using RFC 6887 Port Control Protocol (PCP). Handles IPv4 and IPv6.

== Synopsis

Declared in `<common/pcp.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
std::variant<MappingResult, MappingError>
PCPRequestPortMap(
    xref:PCPMappingNonce.adoc[PCPMappingNonce] const& nonce,
    xref:CNetAddr.adoc[CNetAddr] const& gateway,
    xref:CNetAddr.adoc[CNetAddr] const& bind,
    uint16_t port,
    uint32_t lifetime,
    xref:CThreadInterrupt.adoc[CThreadInterrupt]& interrupt,
    int num_tries = 3,
    std::chrono::milliseconds timeout_per_try = std::chrono::milliseconds(1000));
----

== Description

* nonce: Mapping cookie. Keep this the same over renewals. * gateway: Destination address for PCP requests (usually the default gateway). * bind: Specific local bind address for IPv6 pinholing. Set this as INADDR_ANY for IPv4. * port: Internal port, and desired external port. * lifetime: Requested lifetime in seconds for mapping. The server may assign as shorter or longer lifetime. A lifetime of 0 deletes the mapping. * num_tries: Number of tries in case of no response.

Returns the external_ip:external_port of the mapping if successful, otherwise a MappingError.

== Return Value

The mapping result on success, otherwise a MappingError.

== Parameters

[cols="1,4"]
|===
| Name| Description
| *nonce*
| Mapping cookie; keep this the same across renewals.
| *gateway*
| Destination address for requests (usually the default gateway).
| *bind*
| Local bind address for IPv6 pinholing; INADDR_ANY for IPv4.
| *port*
| Internal port, and desired external port.
| *lifetime*
| Requested lifetime in seconds; 0 deletes the mapping.
| *interrupt*
| Interruption signal used to abort while waiting for a response.
| *num_tries*
| Number of attempts in case of no response.
| *timeout_per_try*
| Time to wait for a response on each attempt.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#