= nng_msg_get_pipe(3)
//
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
//
// This document is supplied under the terms of the MIT License, a
// copy of which should be located in the distribution where this
// file was obtained (LICENSE.txt).  A copy of the license may also be
// found online at https://opensource.org/licenses/MIT.
//

== NAME

nng_msg_get_pipe - get pipe for message

== SYNOPSIS

[source, c]
----
#include <nng/nng.h>

nng_pipe nng_msg_get_pipe(nng_msg *msg);
----

== DESCRIPTION

The `nng_msg_get_pipe()` returns the xref:nng_pipe.5.adoc[`nng_pipe`] object
associated with message _msg_.
On receive, this is the pipe from which a message was received.
On transmit, this would be the pipe that the message should be delivered
to, if a specific peer is required.

NOTE: Not all protocols support overriding the destination pipe.

The most usual use case for this is to obtain information about the peer
from which the message was received.
This can be used to provide different behaviors for different peers, such as
a higher level of authentication for peers located on an untrusted network.
The xref:nng_pipe_getopt.3.adoc[`nng_pipe_getopt()`] function
is useful in this situation.


== RETURN VALUES

This function returns the pipe associated with this message, which will
be a positive value.
If the pipe is non-positive, then that indicates that
no specific pipe is associated with the message.

== ERRORS

None.

== SEE ALSO

[.text-left]
xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)],
xref:nng_msg_set_pipe.3.adoc[nng_msg_set_pipe(3)],
xref:nng_pipe_getopt.3.adoc[nng_pipe_getopt(3)],
xref:nng.7.adoc[nng(7)]