1
/* $Id: stun_msg.h 3553 2011-05-05 06:14:19Z nanang $ */
3
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
6
* This program is free software; you can redistribute it and/or modify
7
* it under the terms of the GNU General Public License as published by
8
* the Free Software Foundation; either version 2 of the License, or
9
* (at your option) any later version.
11
* This program is distributed in the hope that it will be useful,
12
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
* GNU General Public License for more details.
16
* You should have received a copy of the GNU General Public License
17
* along with this program; if not, write to the Free Software
18
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
#ifndef __PJNATH_STUN_MSG_H__
21
#define __PJNATH_STUN_MSG_H__
25
* @brief STUN message components.
28
#include <pjnath/types.h>
35
/* **************************************************************************/
37
* @defgroup PJNATH_STUN_MSG STUN Message Representation and Parsing
38
* @ingroup PJNATH_STUN_BASE
39
* @brief Low-level representation and parsing of STUN messages.
47
#define PJ_STUN_MAGIC 0x2112A442
51
* STUN method constants.
56
* STUN Binding method as defined by RFC 3489-bis.
58
PJ_STUN_BINDING_METHOD = 1,
61
* STUN Shared Secret method as defined by RFC 3489-bis.
63
PJ_STUN_SHARED_SECRET_METHOD = 2,
66
* STUN/TURN Allocate method as defined by draft-ietf-behave-turn
68
PJ_STUN_ALLOCATE_METHOD = 3,
71
* STUN/TURN Refresh method as defined by draft-ietf-behave-turn
73
PJ_STUN_REFRESH_METHOD = 4,
76
* STUN/TURN Send indication as defined by draft-ietf-behave-turn
78
PJ_STUN_SEND_METHOD = 6,
81
* STUN/TURN Data indication as defined by draft-ietf-behave-turn
83
PJ_STUN_DATA_METHOD = 7,
86
* STUN/TURN CreatePermission method as defined by draft-ietf-behave-turn
88
PJ_STUN_CREATE_PERM_METHOD = 8,
91
* STUN/TURN ChannelBind as defined by draft-ietf-behave-turn
93
PJ_STUN_CHANNEL_BIND_METHOD = 9,
103
* Retrieve the STUN method from the message-type field of the STUN
106
#define PJ_STUN_GET_METHOD(msg_type) ((msg_type) & 0xFEEF)
110
* STUN message classes constants.
112
enum pj_stun_msg_class_e
115
* This specifies that the message type is a STUN request message.
117
PJ_STUN_REQUEST_CLASS = 0,
120
* This specifies that the message type is a STUN indication message.
122
PJ_STUN_INDICATION_CLASS = 1,
125
* This specifies that the message type is a STUN successful response.
127
PJ_STUN_SUCCESS_CLASS = 2,
130
* This specifies that the message type is a STUN error response.
132
PJ_STUN_ERROR_CLASS = 3
137
* Determine if the message type is a request.
139
#define PJ_STUN_IS_REQUEST(msg_type) (((msg_type) & 0x0110) == 0x0000)
143
* Determine if the message type is a successful response.
145
#define PJ_STUN_IS_SUCCESS_RESPONSE(msg_type) (((msg_type) & 0x0110) == 0x0100)
148
* The response bit in the message type.
150
#define PJ_STUN_SUCCESS_RESPONSE_BIT (0x0100)
154
* Determine if the message type is an error response.
156
#define PJ_STUN_IS_ERROR_RESPONSE(msg_type) (((msg_type) & 0x0110) == 0x0110)
159
* The error response bit in the message type.
161
#define PJ_STUN_ERROR_RESPONSE_BIT (0x0110)
164
* Determine if the message type is a response.
166
#define PJ_STUN_IS_RESPONSE(msg_type) (((msg_type) & 0x0100) == 0x0100)
170
* Determine if the message type is an indication message.
172
#define PJ_STUN_IS_INDICATION(msg_type) (((msg_type) & 0x0110) == 0x0010)
175
* The error response bit in the message type.
177
#define PJ_STUN_INDICATION_BIT (0x0010)
181
* This enumeration describes STUN message types.
183
typedef enum pj_stun_msg_type
186
* STUN BINDING request.
188
PJ_STUN_BINDING_REQUEST = 0x0001,
191
* Successful response to STUN BINDING-REQUEST.
193
PJ_STUN_BINDING_RESPONSE = 0x0101,
196
* Error response to STUN BINDING-REQUEST.
198
PJ_STUN_BINDING_ERROR_RESPONSE = 0x0111,
201
* Binding Indication (ICE)
203
PJ_STUN_BINDING_INDICATION = 0x0011,
206
* STUN SHARED-SECRET reqeust.
208
PJ_STUN_SHARED_SECRET_REQUEST = 0x0002,
211
* Successful response to STUN SHARED-SECRET reqeust.
213
PJ_STUN_SHARED_SECRET_RESPONSE = 0x0102,
216
* Error response to STUN SHARED-SECRET reqeust.
218
PJ_STUN_SHARED_SECRET_ERROR_RESPONSE = 0x0112,
222
* STUN/TURN Allocate Request
224
PJ_STUN_ALLOCATE_REQUEST = 0x0003,
227
* Successful response to STUN/TURN Allocate Request
229
PJ_STUN_ALLOCATE_RESPONSE = 0x0103,
232
* Failure response to STUN/TURN Allocate Request
234
PJ_STUN_ALLOCATE_ERROR_RESPONSE = 0x0113,
238
* STUN/TURN REFRESH Request
240
PJ_STUN_REFRESH_REQUEST = 0x0004,
243
* Successful response to STUN REFRESH request
245
PJ_STUN_REFRESH_RESPONSE = 0x0104,
248
* Error response to STUN REFRESH request.
250
PJ_STUN_REFRESH_ERROR_RESPONSE = 0x0114,
254
* TURN Send indication
256
PJ_STUN_SEND_INDICATION = 0x0016,
260
* TURN Data indication
262
PJ_STUN_DATA_INDICATION = 0x0017,
266
* TURN CreatePermission request
268
PJ_STUN_CREATE_PERM_REQUEST = 0x0008,
271
* TURN CreatePermission successful response.
273
PJ_STUN_CREATE_PERM_RESPONSE = 0x0108,
276
* TURN CreatePermission failure response
278
PJ_STUN_CREATE_PERM_ERROR_RESPONSE = 0x0118,
282
* STUN/TURN ChannelBind Request
284
PJ_STUN_CHANNEL_BIND_REQUEST = 0x0009,
287
* Successful response to STUN ChannelBind request
289
PJ_STUN_CHANNEL_BIND_RESPONSE = 0x0109,
292
* Error response to STUN ChannelBind request.
294
PJ_STUN_CHANNEL_BIND_ERROR_RESPONSE = 0x0119
301
* This enumeration describes STUN attribute types.
303
typedef enum pj_stun_attr_type
305
PJ_STUN_ATTR_MAPPED_ADDR = 0x0001,/**< MAPPED-ADDRESS. */
306
PJ_STUN_ATTR_RESPONSE_ADDR = 0x0002,/**< RESPONSE-ADDRESS (deprcatd)*/
307
PJ_STUN_ATTR_CHANGE_REQUEST = 0x0003,/**< CHANGE-REQUEST (deprecated)*/
308
PJ_STUN_ATTR_SOURCE_ADDR = 0x0004,/**< SOURCE-ADDRESS (deprecated)*/
309
PJ_STUN_ATTR_CHANGED_ADDR = 0x0005,/**< CHANGED-ADDRESS (deprecatd)*/
310
PJ_STUN_ATTR_USERNAME = 0x0006,/**< USERNAME attribute. */
311
PJ_STUN_ATTR_PASSWORD = 0x0007,/**< was PASSWORD attribute. */
312
PJ_STUN_ATTR_MESSAGE_INTEGRITY = 0x0008,/**< MESSAGE-INTEGRITY. */
313
PJ_STUN_ATTR_ERROR_CODE = 0x0009,/**< ERROR-CODE. */
314
PJ_STUN_ATTR_UNKNOWN_ATTRIBUTES = 0x000A,/**< UNKNOWN-ATTRIBUTES. */
315
PJ_STUN_ATTR_REFLECTED_FROM = 0x000B,/**< REFLECTED-FROM (deprecatd)*/
316
PJ_STUN_ATTR_CHANNEL_NUMBER = 0x000C,/**< TURN CHANNEL-NUMBER */
317
PJ_STUN_ATTR_LIFETIME = 0x000D,/**< TURN LIFETIME attr. */
318
PJ_STUN_ATTR_MAGIC_COOKIE = 0x000F,/**< MAGIC-COOKIE attr (deprec)*/
319
PJ_STUN_ATTR_BANDWIDTH = 0x0010,/**< TURN BANDWIDTH (deprec) */
320
PJ_STUN_ATTR_XOR_PEER_ADDR = 0x0012,/**< TURN XOR-PEER-ADDRESS */
321
PJ_STUN_ATTR_DATA = 0x0013,/**< DATA attribute. */
322
PJ_STUN_ATTR_REALM = 0x0014,/**< REALM attribute. */
323
PJ_STUN_ATTR_NONCE = 0x0015,/**< NONCE attribute. */
324
PJ_STUN_ATTR_XOR_RELAYED_ADDR = 0x0016,/**< TURN XOR-RELAYED-ADDRESS */
325
PJ_STUN_ATTR_REQ_ADDR_TYPE = 0x0017,/**< REQUESTED-ADDRESS-TYPE */
326
PJ_STUN_ATTR_EVEN_PORT = 0x0018,/**< TURN EVEN-PORT */
327
PJ_STUN_ATTR_REQ_TRANSPORT = 0x0019,/**< TURN REQUESTED-TRANSPORT */
328
PJ_STUN_ATTR_DONT_FRAGMENT = 0x001A,/**< TURN DONT-FRAGMENT */
329
PJ_STUN_ATTR_XOR_MAPPED_ADDR = 0x0020,/**< XOR-MAPPED-ADDRESS */
330
PJ_STUN_ATTR_TIMER_VAL = 0x0021,/**< TIMER-VAL attribute. */
331
PJ_STUN_ATTR_RESERVATION_TOKEN = 0x0022,/**< TURN RESERVATION-TOKEN */
332
PJ_STUN_ATTR_XOR_REFLECTED_FROM = 0x0023,/**< XOR-REFLECTED-FROM */
333
PJ_STUN_ATTR_PRIORITY = 0x0024,/**< PRIORITY */
334
PJ_STUN_ATTR_USE_CANDIDATE = 0x0025,/**< USE-CANDIDATE */
335
PJ_STUN_ATTR_ICMP = 0x0030,/**< ICMP (TURN) */
337
PJ_STUN_ATTR_END_MANDATORY_ATTR,
339
PJ_STUN_ATTR_START_EXTENDED_ATTR= 0x8021,
341
PJ_STUN_ATTR_SOFTWARE = 0x8022,/**< SOFTWARE attribute. */
342
PJ_STUN_ATTR_ALTERNATE_SERVER = 0x8023,/**< ALTERNATE-SERVER. */
343
PJ_STUN_ATTR_REFRESH_INTERVAL = 0x8024,/**< REFRESH-INTERVAL. */
344
PJ_STUN_ATTR_FINGERPRINT = 0x8028,/**< FINGERPRINT attribute. */
345
PJ_STUN_ATTR_ICE_CONTROLLED = 0x8029,/**< ICE-CCONTROLLED attribute.*/
346
PJ_STUN_ATTR_ICE_CONTROLLING = 0x802a,/**< ICE-CCONTROLLING attribute*/
348
PJ_STUN_ATTR_END_EXTENDED_ATTR
354
* STUN error codes, which goes into STUN ERROR-CODE attribute.
356
typedef enum pj_stun_status
358
PJ_STUN_SC_TRY_ALTERNATE = 300, /**< Try Alternate */
359
PJ_STUN_SC_BAD_REQUEST = 400, /**< Bad Request */
360
PJ_STUN_SC_UNAUTHORIZED = 401, /**< Unauthorized */
361
PJ_STUN_SC_FORBIDDEN = 403, /**< Forbidden (TURN) */
362
PJ_STUN_SC_UNKNOWN_ATTRIBUTE = 420, /**< Unknown Attribute */
364
/* These were obsolete in recent rfc3489bis */
365
//PJ_STUN_SC_STALE_CREDENTIALS = 430, /**< Stale Credentials */
366
//PJ_STUN_SC_INTEGRITY_CHECK_FAILURE= 431, /**< Integrity Chk Fail */
367
//PJ_STUN_SC_MISSING_USERNAME = 432, /**< Missing Username */
368
//PJ_STUN_SC_USE_TLS = 433, /**< Use TLS */
369
//PJ_STUN_SC_MISSING_REALM = 434, /**< Missing Realm */
370
//PJ_STUN_SC_MISSING_NONCE = 435, /**< Missing Nonce */
371
//PJ_STUN_SC_UNKNOWN_USERNAME = 436, /**< Unknown Username */
373
PJ_STUN_SC_ALLOCATION_MISMATCH = 437, /**< TURN Alloc Mismatch */
374
PJ_STUN_SC_STALE_NONCE = 438, /**< Stale Nonce */
375
PJ_STUN_SC_TRANSITIONING = 439, /**< Transitioning. */
376
PJ_STUN_SC_WRONG_CREDENTIALS = 441, /**< TURN Wrong Credentials */
377
PJ_STUN_SC_UNSUPP_TRANSPORT_PROTO = 442, /**< Unsupported Transport or
379
PJ_STUN_SC_OPER_TCP_ONLY = 445, /**< Operation for TCP Only */
380
PJ_STUN_SC_CONNECTION_FAILURE = 446, /**< Connection Failure */
381
PJ_STUN_SC_CONNECTION_TIMEOUT = 447, /**< Connection Timeout */
382
PJ_STUN_SC_ALLOCATION_QUOTA_REACHED = 486, /**< Allocation Quota Reached
384
PJ_STUN_SC_ROLE_CONFLICT = 487, /**< Role Conflict */
385
PJ_STUN_SC_SERVER_ERROR = 500, /**< Server Error */
386
PJ_STUN_SC_INSUFFICIENT_CAPACITY = 508, /**< Insufficient Capacity
388
PJ_STUN_SC_GLOBAL_FAILURE = 600 /**< Global Failure */
393
* This structure describes STUN message header. A STUN message has the
399
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
400
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
401
|0 0| STUN Message Type | Message Length |
402
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
404
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
406
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
408
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
410
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
414
typedef struct pj_stun_msg_hdr
417
* STUN message type, which the first two bits must be zeroes.
422
* The message length is the size, in bytes, of the message not
423
* including the 20 byte STUN header.
428
* The magic cookie is a fixed value, 0x2112A442 (PJ_STUN_MAGIC constant).
429
* In the previous version of this specification [15] this field was part
430
* of the transaction ID.
435
* The transaction ID is a 96 bit identifier. STUN transactions are
436
* identified by their unique 96-bit transaction ID. For request/
437
* response transactions, the transaction ID is chosen by the STUN
438
* client and MUST be unique for each new STUN transaction generated by
439
* that STUN client. The transaction ID MUST be uniformly and randomly
440
* distributed between 0 and 2**96 - 1.
442
pj_uint8_t tsx_id[12];
448
* This structre describes STUN attribute header. Each attribute is
449
* TLV encoded, with a 16 bit type, 16 bit length, and variable value.
450
* Each STUN attribute ends on a 32 bit boundary:
455
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
456
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
458
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
462
typedef struct pj_stun_attr_hdr
465
* STUN attribute type.
470
* The Length refers to the length of the actual useful content of the
471
* Value portion of the attribute, measured in bytes. The value
472
* in the Length field refers to the length of the Value part of the
473
* attribute prior to padding - i.e., the useful content.
481
* This structure describes STUN generic IP address attribute, used for
482
* example to represent STUN MAPPED-ADDRESS attribute.
484
* The generic IP address attribute indicates the transport address.
485
* It consists of an eight bit address family, and a sixteen bit port,
486
* followed by a fixed length value representing the IP address. If the
487
* address family is IPv4, the address is 32 bits, in network byte
488
* order. If the address family is IPv6, the address is 128 bits in
489
* network byte order.
491
* The format of the generic IP address attribute is:
496
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
497
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
498
|x x x x x x x x| Family | Port |
499
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
501
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
505
typedef struct pj_stun_sockaddr_attr
508
* Standard STUN attribute header.
510
pj_stun_attr_hdr hdr;
513
* Flag to indicate whether this attribute should be sent in XOR-ed
514
* format, or has been received in XOR-ed format.
521
pj_sockaddr sockaddr;
523
} pj_stun_sockaddr_attr;
527
* This structure represents a generic STUN attributes with no payload,
528
* and it is used for example by ICE USE-CANDIDATE attribute.
530
typedef struct pj_stun_empty_attr
533
* Standard STUN attribute header.
535
pj_stun_attr_hdr hdr;
537
} pj_stun_empty_attr;
541
* This structure represents generic STUN string attributes, such as STUN
542
* USERNAME, PASSWORD, SOFTWARE, REALM, and NONCE attributes.
544
typedef struct pj_stun_string_attr
547
* Standard STUN attribute header.
549
pj_stun_attr_hdr hdr;
556
} pj_stun_string_attr;
560
* This structure represents a generic STUN attributes with 32bit (unsigned)
561
* integer value, such as STUN FINGERPRINT and REFRESH-INTERVAL attributes.
563
typedef struct pj_stun_uint_attr
566
* Standard STUN attribute header.
568
pj_stun_attr_hdr hdr;
571
* The 32bit value, in host byte order.
579
* This structure represents a generic STUN attributes with 64bit (unsigned)
580
* integer value, such as ICE-CONTROLLED and ICE-CONTROLLING attributes.
582
typedef struct pj_stun_uint64_attr
585
* Standard STUN attribute header.
587
pj_stun_attr_hdr hdr;
590
* The 64bit value, in host byte order, represented with pj_timestamp.
594
} pj_stun_uint64_attr;
598
* This structure represents generic STUN attributes to hold a raw binary
601
typedef struct pj_stun_binary_attr
604
* Standard STUN attribute header.
606
pj_stun_attr_hdr hdr;
609
* Special signature to indicate that this is a valid attribute even
610
* though we don't have meta-data to describe this attribute.
615
* Length of the data.
624
} pj_stun_binary_attr;
628
* This structure describes STUN MESSAGE-INTEGRITY attribute.
629
* The MESSAGE-INTEGRITY attribute contains an HMAC-SHA1 [10] of the
630
* STUN message. The MESSAGE-INTEGRITY attribute can be present in any
631
* STUN message type. Since it uses the SHA1 hash, the HMAC will be 20
634
typedef struct pj_stun_msgint_attr
637
* Standard STUN attribute header.
639
pj_stun_attr_hdr hdr;
642
* The 20 bytes hmac value.
646
} pj_stun_msgint_attr;
650
* This structure describes STUN FINGERPRINT attribute. The FINGERPRINT
651
* attribute can be present in all STUN messages. It is computed as
652
* the CRC-32 of the STUN message up to (but excluding) the FINGERPRINT
653
* attribute itself, xor-d with the 32 bit value 0x5354554e
655
typedef struct pj_stun_uint_attr pj_stun_fingerprint_attr;
659
* This structure represents STUN ERROR-CODE attribute. The ERROR-CODE
660
* attribute is present in the Binding Error Response and Shared Secret
661
* Error Response. It is a numeric value in the range of 100 to 699
662
* plus a textual reason phrase encoded in UTF-8
667
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
668
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
670
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
671
| Reason Phrase (variable) ..
672
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
676
typedef struct pj_stun_errcode_attr
679
* Standard STUN attribute header.
681
pj_stun_attr_hdr hdr;
693
} pj_stun_errcode_attr;
697
* This describes STUN REALM attribute.
698
* The REALM attribute is present in requests and responses. It
699
* contains text which meets the grammar for "realm" as described in RFC
700
* 3261 [11], and will thus contain a quoted string (including the
703
typedef struct pj_stun_string_attr pj_stun_realm_attr;
707
* This describes STUN NONCE attribute.
708
* The NONCE attribute is present in requests and in error responses.
709
* It contains a sequence of qdtext or quoted-pair, which are defined in
710
* RFC 3261 [11]. See RFC 2617 [7] for guidance on selection of nonce
711
* values in a server.
713
typedef struct pj_stun_string_attr pj_stun_nonce_attr;
717
* This describes STUN UNKNOWN-ATTRIBUTES attribute.
718
* The UNKNOWN-ATTRIBUTES attribute is present only in an error response
719
* when the response code in the ERROR-CODE attribute is 420.
720
* The attribute contains a list of 16 bit values, each of which
721
* represents an attribute type that was not understood by the server.
722
* If the number of unknown attributes is an odd number, one of the
723
* attributes MUST be repeated in the list, so that the total length of
724
* the list is a multiple of 4 bytes.
726
typedef struct pj_stun_unknown_attr
729
* Standard STUN attribute header.
731
pj_stun_attr_hdr hdr;
734
* Number of unknown attributes in the array.
739
* Array of unknown attribute IDs.
741
pj_uint16_t attrs[PJ_STUN_MAX_ATTR];
743
} pj_stun_unknown_attr;
747
* This structure describes STUN MAPPED-ADDRESS attribute.
748
* The MAPPED-ADDRESS attribute indicates the mapped transport address.
750
typedef struct pj_stun_sockaddr_attr pj_stun_mapped_addr_attr;
754
* This describes STUN XOR-MAPPED-ADDRESS attribute (which has the same
755
* format as STUN MAPPED-ADDRESS attribute).
756
* The XOR-MAPPED-ADDRESS attribute is present in responses. It
757
* provides the same information that would present in the MAPPED-
758
* ADDRESS attribute but because the NAT's public IP address is
759
* obfuscated through the XOR function, STUN messages are able to pass
760
* through NATs which would otherwise interfere with STUN.
762
typedef struct pj_stun_sockaddr_attr pj_stun_xor_mapped_addr_attr;
766
* This describes STUN SOFTWARE attribute.
767
* The SOFTWARE attribute contains a textual description of the software
768
* being used by the agent sending the message. It is used by clients
769
* and servers. Its value SHOULD include manufacturer and version
771
typedef struct pj_stun_string_attr pj_stun_software_attr;
775
* This describes STUN ALTERNATE-SERVER attribute.
776
* The alternate server represents an alternate transport address for a
777
* different STUN server to try. It is encoded in the same way as
780
typedef struct pj_stun_sockaddr_attr pj_stun_alt_server_attr;
784
* This describes STUN REFRESH-INTERVAL attribute.
785
* The REFRESH-INTERVAL indicates the number of milliseconds that the
786
* server suggests the client should use between refreshes of the NAT
787
* bindings between the client and server.
789
typedef struct pj_stun_uint_attr pj_stun_refresh_interval_attr;
793
* This structure describes STUN RESPONSE-ADDRESS attribute.
794
* The RESPONSE-ADDRESS attribute indicates where the response to a
795
* Binding Request should be sent. Its syntax is identical to MAPPED-
798
* Note that the usage of this attribute has been deprecated by the
799
* RFC 3489-bis standard.
801
typedef struct pj_stun_sockaddr_attr pj_stun_response_addr_attr;
805
* This structure describes STUN CHANGED-ADDRESS attribute.
806
* The CHANGED-ADDRESS attribute indicates the IP address and port where
807
* responses would have been sent from if the "change IP" and "change
808
* port" flags had been set in the CHANGE-REQUEST attribute of the
809
* Binding Request. The attribute is always present in a Binding
810
* Response, independent of the value of the flags. Its syntax is
811
* identical to MAPPED-ADDRESS.
813
* Note that the usage of this attribute has been deprecated by the
814
* RFC 3489-bis standard.
816
typedef struct pj_stun_sockaddr_attr pj_stun_changed_addr_attr;
820
* This structure describes STUN CHANGE-REQUEST attribute.
821
* The CHANGE-REQUEST attribute is used by the client to request that
822
* the server use a different address and/or port when sending the
825
* Bit 29 of the value is the "change IP" flag. If true, it requests
826
* the server to send the Binding Response with a different IP address
827
* than the one the Binding Request was received on.
829
* Bit 30 of the value is the "change port" flag. If true, it requests
830
* the server to send the Binding Response with a different port than
831
* the one the Binding Request was received on.
833
* Note that the usage of this attribute has been deprecated by the
834
* RFC 3489-bis standard.
836
typedef struct pj_stun_uint_attr pj_stun_change_request_attr;
839
* This structure describes STUN SOURCE-ADDRESS attribute.
840
* The SOURCE-ADDRESS attribute is present in Binding Responses. It
841
* indicates the source IP address and port that the server is sending
842
* the response from. Its syntax is identical to that of MAPPED-
845
* Note that the usage of this attribute has been deprecated by the
846
* RFC 3489-bis standard.
848
typedef struct pj_stun_sockaddr_attr pj_stun_src_addr_attr;
852
* This describes the STUN REFLECTED-FROM attribute.
853
* The REFLECTED-FROM attribute is present only in Binding Responses,
854
* when the Binding Request contained a RESPONSE-ADDRESS attribute. The
855
* attribute contains the identity (in terms of IP address) of the
856
* source where the request came from. Its purpose is to provide
857
* traceability, so that a STUN server cannot be used as a reflector for
858
* denial-of-service attacks.
860
typedef struct pj_stun_sockaddr_attr pj_stun_reflected_from_attr;
864
* This describes STUN USERNAME attribute.
865
* The USERNAME attribute is used for message integrity. It identifies
866
* the shared secret used in the message integrity check. Consequently,
867
* the USERNAME MUST be included in any request that contains the
868
* MESSAGE-INTEGRITY attribute.
870
typedef struct pj_stun_string_attr pj_stun_username_attr;
874
* This describes STUN PASSWORD attribute.
875
* If the message type is Shared Secret Response it MUST include the
876
* PASSWORD attribute.
878
typedef struct pj_stun_string_attr pj_stun_password_attr;
882
* This describes TURN CHANNEL-NUMBER attribute. In this library,
883
* this attribute is represented with 32bit integer. Application may
884
* use #PJ_STUN_GET_CH_NB() and #PJ_STUN_SET_CH_NB() to extract/set
885
* channel number value from the 32bit integral value.
887
* The CHANNEL-NUMBER attribute contains the number of the channel.
888
* It is a 16-bit unsigned integer, followed by a two-octet RFFU field
889
* which MUST be set to 0 on transmission and ignored on reception.
893
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
894
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
895
| Channel Number | RFFU |
896
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
899
typedef struct pj_stun_uint_attr pj_stun_channel_number_attr;
902
* Get 16bit channel number from 32bit integral value.
903
* Note that uint32 attributes are always stored in host byte order
904
* after they have been parsed from the PDU, so no need to do ntohs()
907
#define PJ_STUN_GET_CH_NB(u32) ((pj_uint16_t)(u32>>16))
910
* Convert 16bit channel number into 32bit integral value.
911
* Note that uint32 attributes will be converted to network byte order
912
* when the attribute is written to packet, so no need to do htons()
915
#define PJ_STUN_SET_CH_NB(chnum) (((pj_uint32_t)chnum) << 16)
919
* This describes STUN LIFETIME attribute.
920
* The lifetime attribute represents the duration for which the server
921
* will maintain an allocation in the absence of data traffic either
922
* from or to the client. It is a 32 bit value representing the number
923
* of seconds remaining until expiration.
925
typedef struct pj_stun_uint_attr pj_stun_lifetime_attr;
929
* This describes STUN BANDWIDTH attribute.
930
* The bandwidth attribute represents the peak bandwidth, measured in
931
* kbits per second, that the client expects to use on the binding. The
932
* value represents the sum in the receive and send directions.
934
typedef struct pj_stun_uint_attr pj_stun_bandwidth_attr;
938
* This describes the STUN XOR-PEER-ADDRESS attribute.
939
* The XOR-PEER-ADDRESS specifies the address and port of the peer as seen
940
* from the TURN server. It is encoded in the same way as XOR-MAPPED-
943
typedef struct pj_stun_sockaddr_attr pj_stun_xor_peer_addr_attr;
947
* This describes the STUN DATA attribute.
948
* The DATA attribute is present in Send Indications and Data
949
* Indications. It contains raw payload data that is to be sent (in the
950
* case of a Send Request) or was received (in the case of a Data
953
typedef struct pj_stun_binary_attr pj_stun_data_attr;
957
* This describes the STUN XOR-RELAYED-ADDRESS attribute. The
958
* XOR-RELAYED-ADDRESS is present in Allocate responses. It specifies the
959
* address and port that the server allocated to the client. It is
960
* encoded in the same way as XOR-MAPPED-ADDRESS.
962
typedef struct pj_stun_sockaddr_attr pj_stun_xor_relayed_addr_attr;
966
* This describes the REQUESTED-ADDRESS-TYPE attribute.
967
* The REQUESTED-ADDRESS-TYPE attribute is used by clients to request
968
* the allocation of a specific address type from a server. The
969
* following is the format of the REQUESTED-ADDRESS-TYPE attribute.
974
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
975
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
976
| Family | Reserved |
977
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
981
typedef struct pj_stun_uint_attr pj_stun_req_addr_type_attr;
985
* This describes the TURN REQUESTED-TRANSPORT attribute, encoded in
986
* STUN generic integer attribute.
988
* This attribute allows the client to request that the port in the
989
* relayed-transport-address be even, and (optionally) that the server
990
* reserve the next-higher port number. The attribute is 8 bits long.
1002
* The attribute contains a single 1-bit flag:
1004
* R: If 1, the server is requested to reserve the next higher port
1005
* number (on the same IP address) for a subsequent allocation. If
1006
* 0, no such reservation is requested.
1008
* The other 7 bits of the attribute must be set to zero on transmission
1009
* and ignored on reception.
1011
typedef struct pj_stun_uint_attr pj_stun_even_port_attr;
1015
* This describes the TURN REQUESTED-TRANSPORT attribute, encoded in
1016
* STUN generic integer attribute.
1018
* This attribute is used by the client to request a specific transport
1019
* protocol for the allocated transport address. It has the following
1025
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
1026
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1028
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1033
* The Protocol field specifies the desired protocol. The codepoints
1034
* used in this field are taken from those allowed in the Protocol field
1035
* in the IPv4 header and the NextHeader field in the IPv6 header
1036
* [Protocol-Numbers]. This specification only allows the use of
1037
* codepoint 17 (User Datagram Protocol).
1039
* The RFFU field is set to zero on transmission and ignored on
1040
* receiption. It is reserved for future uses.
1042
typedef struct pj_stun_uint_attr pj_stun_req_transport_attr;
1045
* Get protocol value from 32bit TURN REQUESTED-TRANSPORT attribute.
1047
#define PJ_STUN_GET_RT_PROTO(u32) (u32 >> 24)
1050
* Convert protocol value to be placed in 32bit TURN REQUESTED-TRANSPORT
1053
#define PJ_STUN_SET_RT_PROTO(proto) (((pj_uint32_t)(proto)) << 24)
1057
* This describes the TURN DONT-FRAGMENT attribute.
1059
* This attribute is used by the client to request that the server set
1060
* the DF (Don't Fragment) bit in the IP header when relaying the
1061
* application data onward to the peer. This attribute has no value
1062
* part and thus the attribute length field is 0.
1064
typedef struct pj_stun_empty_attr pj_stun_dont_fragment_attr;
1068
* This describes the TURN RESERVATION-TOKEN attribute.
1069
* The RESERVATION-TOKEN attribute contains a token that uniquely
1070
* identifies a relayed transport address being held in reserve by the
1071
* server. The server includes this attribute in a success response to
1072
* tell the client about the token, and the client includes this
1073
* attribute in a subsequent Allocate request to request the server use
1074
* that relayed transport address for the allocation.
1076
* The attribute value is a 64-bit-long field containing the token
1079
typedef struct pj_stun_uint64_attr pj_stun_res_token_attr;
1082
* This describes the XOR-REFLECTED-FROM attribute, as described by
1083
* draft-macdonald-behave-nat-behavior-discovery-00.
1084
* The XOR-REFLECTED-FROM attribute is used in place of the REFLECTED-
1085
* FROM attribute. It provides the same information, but because the
1086
* NAT's public address is obfuscated through the XOR function, It can
1087
* pass through a NAT that would otherwise attempt to translate it to
1088
* the private network address. XOR-REFLECTED-FROM has identical syntax
1089
* to XOR-MAPPED-ADDRESS.
1091
typedef struct pj_stun_sockaddr_attr pj_stun_xor_reflected_from_attr;
1094
* This describes the PRIORITY attribute from draft-ietf-mmusic-ice-13.
1095
* The PRIORITY attribute indicates the priority that is to be
1096
* associated with a peer reflexive candidate, should one be discovered
1097
* by this check. It is a 32 bit unsigned integer, and has an attribute
1100
typedef struct pj_stun_uint_attr pj_stun_priority_attr;
1103
* This describes the USE-CANDIDATE attribute from draft-ietf-mmusic-ice-13.
1104
* The USE-CANDIDATE attribute indicates that the candidate pair
1105
* resulting from this check should be used for transmission of media.
1106
* The attribute has no content (the Length field of the attribute is
1107
* zero); it serves as a flag.
1109
typedef struct pj_stun_empty_attr pj_stun_use_candidate_attr;
1112
* This describes the STUN TIMER-VAL attribute.
1113
* The TIMER-VAL attribute is used only in conjunction with the Set
1114
* Active Destination response. It conveys from the server, to the
1115
* client, the value of the timer used in the server state machine.
1117
typedef struct pj_stun_uint_attr pj_stun_timer_val_attr;
1120
* This describes ICE-CONTROLLING attribute.
1122
typedef struct pj_stun_uint64_attr pj_stun_ice_controlling_attr;
1125
* This describes ICE-CONTROLLED attribute.
1127
typedef struct pj_stun_uint64_attr pj_stun_ice_controlled_attr;
1130
* This describes TURN ICMP attribute
1132
typedef struct pj_stun_uint_attr pj_stun_icmp_attr;
1135
* This structure describes a parsed STUN message. All integral fields
1136
* in this structure (including IP addresses) will be in the host
1139
typedef struct pj_stun_msg
1142
* STUN message header.
1144
pj_stun_msg_hdr hdr;
1147
* Number of attributes in the STUN message.
1149
unsigned attr_count;
1152
* Array of STUN attributes.
1154
pj_stun_attr_hdr *attr[PJ_STUN_MAX_ATTR];
1159
/** STUN decoding options */
1160
enum pj_stun_decode_options
1163
* Tell the decoder that the message was received from datagram
1164
* oriented transport (such as UDP).
1166
PJ_STUN_IS_DATAGRAM = 1,
1169
* Tell pj_stun_msg_decode() to check the validity of the STUN
1170
* message by calling pj_stun_msg_check() before starting to
1171
* decode the packet.
1173
PJ_STUN_CHECK_PACKET = 2,
1176
* This option current is only valid for #pj_stun_session_on_rx_pkt().
1177
* When specified, it tells the session NOT to authenticate the
1180
PJ_STUN_NO_AUTHENTICATE = 4,
1183
* Disable FINGERPRINT verification. This option can be used when calling
1184
* #pj_stun_msg_check() and #pj_stun_msg_decode() to disable the
1185
* verification of FINGERPRINT, for example when the STUN usage says when
1186
* FINGERPRINT mechanism shall not be used.
1188
PJ_STUN_NO_FINGERPRINT_CHECK = 8
1193
* Get STUN message method name.
1195
* @param msg_type The STUN message type (in host byte order)
1197
* @return The STUN message method name string.
1199
PJ_DECL(const char*) pj_stun_get_method_name(unsigned msg_type);
1203
* Get STUN message class name.
1205
* @param msg_type The STUN message type (in host byte order)
1207
* @return The STUN message class name string.
1209
PJ_DECL(const char*) pj_stun_get_class_name(unsigned msg_type);
1213
* Get STUN attribute name.
1215
* @return attr_type The STUN attribute type (in host byte order).
1217
* @return The STUN attribute type name string.
1219
PJ_DECL(const char*) pj_stun_get_attr_name(unsigned attr_type);
1223
* Get STUN standard reason phrase for the specified error code.
1225
* @param err_code The STUN error code.
1227
* @return The STUN error reason phrase.
1229
PJ_DECL(pj_str_t) pj_stun_get_err_reason(int err_code);
1233
* Internal: set the padding character for string attribute.
1234
* The default padding character is PJ_STUN_STRING_ATTR_PAD_CHR.
1236
* @return The previous padding character.
1238
PJ_DECL(int) pj_stun_set_padding_char(int chr);
1242
* Initialize a generic STUN message.
1244
* @param msg The message structure to be initialized.
1245
* @param msg_type The 14bit message type (see pj_stun_msg_type
1247
* @param magic Magic value to be put to the mesage; for requests,
1248
* the value normally should be PJ_STUN_MAGIC.
1249
* @param tsx_id Optional transaction ID, or NULL to let the
1250
* function generates a random transaction ID.
1252
* @return PJ_SUCCESS on success.
1254
PJ_DECL(pj_status_t) pj_stun_msg_init(pj_stun_msg *msg,
1257
const pj_uint8_t tsx_id[12]);
1260
* Create a generic STUN message.
1262
* @param pool Pool to create the STUN message.
1263
* @param msg_type The 14bit message type.
1264
* @param magic Magic value to be put to the mesage; for requests,
1265
* the value should be PJ_STUN_MAGIC.
1266
* @param tsx_id Optional transaction ID, or NULL to let the
1267
* function generates a random transaction ID.
1268
* @param p_msg Pointer to receive the message.
1270
* @return PJ_SUCCESS on success.
1272
PJ_DECL(pj_status_t) pj_stun_msg_create(pj_pool_t *pool,
1275
const pj_uint8_t tsx_id[12],
1276
pj_stun_msg **p_msg);
1279
* Clone a STUN message with all of its attributes.
1281
* @param pool Pool to allocate memory for the new message.
1282
* @param msg The message to be cloned.
1284
* @return The duplicate message.
1286
PJ_DECL(pj_stun_msg*) pj_stun_msg_clone(pj_pool_t *pool,
1287
const pj_stun_msg *msg);
1290
* Create STUN response message.
1292
* @param pool Pool to create the mesage.
1293
* @param req_msg The request message.
1294
* @param err_code STUN error code. If this value is not zero,
1295
* then error response will be created, otherwise
1296
* successful response will be created.
1297
* @param err_msg Optional error message to explain err_code.
1298
* If this value is NULL and err_code is not zero,
1299
* the error string will be taken from the default
1300
* STUN error message.
1301
* @param p_response Pointer to receive the response.
1303
* @return PJ_SUCCESS on success, or the appropriate error.
1305
PJ_DECL(pj_status_t) pj_stun_msg_create_response(pj_pool_t *pool,
1306
const pj_stun_msg *req_msg,
1308
const pj_str_t *err_msg,
1309
pj_stun_msg **p_response);
1313
* Add STUN attribute to STUN message.
1315
* @param msg The STUN message.
1316
* @param attr The STUN attribute to be added to the message.
1318
* @return PJ_SUCCESS on success, or PJ_ETOOMANY if there are
1319
* already too many attributes in the message.
1321
PJ_DECL(pj_status_t) pj_stun_msg_add_attr(pj_stun_msg *msg,
1322
pj_stun_attr_hdr *attr);
1326
* Print the STUN message structure to a packet buffer, ready to be
1327
* sent to remote destination. This function will take care about
1328
* calculating the MESSAGE-INTEGRITY digest as well as FINGERPRINT
1329
* value, if these attributes are present in the message.
1331
* If application wants to apply credential to the message, it MUST
1332
* include a blank MESSAGE-INTEGRITY attribute in the message as the
1333
* last attribute or the attribute before FINGERPRINT. This function will
1334
* calculate the HMAC digest from the message using the supplied key in
1335
* the parameter. The key should be set to the password if short term
1336
* credential is used, or calculated from the MD5 hash of the realm,
1337
* username, and password using #pj_stun_create_key() if long term
1338
* credential is used.
1340
* If FINGERPRINT attribute is present, this function will calculate
1341
* the FINGERPRINT CRC attribute for the message. The FINGERPRINT MUST
1342
* be added as the last attribute of the message.
1344
* @param msg The STUN message to be printed. Upon return,
1345
* some fields in the header (such as message
1346
* length) will be updated.
1347
* @param pkt_buf The buffer to be filled with the packet.
1348
* @param buf_size Size of the buffer.
1349
* @param options Options, which currently must be zero.
1350
* @param key Authentication key to calculate MESSAGE-INTEGRITY
1351
* value. Application can create this key by using
1352
* #pj_stun_create_key() function.
1353
* @param p_msg_len Upon return, it will be filed with the size of
1354
* the packet in bytes, or negative value on error.
1356
* @return PJ_SUCCESS on success or the appropriate error code.
1358
PJ_DECL(pj_status_t) pj_stun_msg_encode(pj_stun_msg *msg,
1359
pj_uint8_t *pkt_buf,
1362
const pj_str_t *key,
1363
pj_size_t *p_msg_len);
1366
* Check that the PDU is potentially a valid STUN message. This function
1367
* is useful when application needs to multiplex STUN packets with other
1368
* application traffic. When this function returns PJ_SUCCESS, there is a
1369
* big chance that the packet is a STUN packet.
1371
* Note that we cannot be sure that the PDU is a really valid STUN message
1372
* until we actually parse the PDU.
1374
* @param pdu The packet buffer.
1375
* @param pdu_len The length of the packet buffer.
1376
* @param options Additional options to be applied in the checking,
1377
* which can be taken from pj_stun_decode_options. One
1378
* of the useful option is PJ_STUN_IS_DATAGRAM which
1379
* means that the pdu represents a whole STUN packet.
1381
* @return PJ_SUCCESS if the PDU is a potentially valid STUN
1384
PJ_DECL(pj_status_t) pj_stun_msg_check(const pj_uint8_t *pdu,
1385
pj_size_t pdu_len, unsigned options);
1389
* Decode incoming packet into STUN message.
1391
* @param pool Pool to allocate the message.
1392
* @param pdu The incoming packet to be parsed.
1393
* @param pdu_len The length of the incoming packet.
1394
* @param options Parsing flags, according to pj_stun_decode_options.
1395
* @param p_msg Pointer to receive the parsed message.
1396
* @param p_parsed_len Optional pointer to receive how many bytes have
1397
* been parsed for the STUN message. This is useful
1398
* when the packet is received over stream oriented
1400
* @param p_response Optional pointer to receive an instance of response
1401
* message, if one can be created. If the packet being
1402
* decoded is a request message, and it contains error,
1403
* and a response can be created, then the STUN
1404
* response message will be returned on this argument.
1406
* @return PJ_SUCCESS if a STUN message has been successfully
1409
PJ_DECL(pj_status_t) pj_stun_msg_decode(pj_pool_t *pool,
1410
const pj_uint8_t *pdu,
1413
pj_stun_msg **p_msg,
1414
pj_size_t *p_parsed_len,
1415
pj_stun_msg **p_response);
1418
* Dump STUN message to a printable string output.
1420
* @param msg The STUN message
1421
* @param buffer Buffer where the printable string output will
1423
* @param length Specify the maximum length of the buffer.
1424
* @param printed_len Optional pointer, which on output will be filled
1425
* up with the actual length of the output string.
1427
* @return The message string output.
1429
#if PJ_LOG_MAX_LEVEL > 0
1430
PJ_DECL(char*) pj_stun_msg_dump(const pj_stun_msg *msg,
1433
unsigned *printed_len);
1435
# define pj_stun_msg_dump(msg, buf, length, printed_len) ""
1440
* Find STUN attribute in the STUN message, starting from the specified
1443
* @param msg The STUN message.
1444
* @param attr_type The attribute type to be found, from pj_stun_attr_type.
1445
* @param start_index The start index of the attribute in the message.
1446
* Specify zero to start searching from the first
1449
* @return The attribute instance, or NULL if it cannot be
1452
PJ_DECL(pj_stun_attr_hdr*) pj_stun_msg_find_attr(const pj_stun_msg *msg,
1454
unsigned start_index);
1458
* Clone a STUN attribute.
1460
* @param pool Pool to allocate memory.
1461
* @param attr Attribute to clone.
1463
* @return Duplicate attribute.
1465
PJ_DECL(pj_stun_attr_hdr*) pj_stun_attr_clone(pj_pool_t *pool,
1466
const pj_stun_attr_hdr *attr);
1470
* Initialize generic STUN IP address attribute. The \a addr_len and
1471
* \a addr parameters specify whether the address is IPv4 or IPv4
1474
* @param attr The socket address attribute to initialize.
1475
* @param attr_type Attribute type, from #pj_stun_attr_type.
1476
* @param xor_ed If non-zero, the port and address will be XOR-ed
1477
* with magic, to make the XOR-MAPPED-ADDRESS attribute.
1478
* @param addr A pj_sockaddr_in or pj_sockaddr_in6 structure.
1479
* @param addr_len Length of \a addr parameter.
1481
* @return PJ_SUCCESS on success or the appropriate error code.
1483
PJ_DECL(pj_status_t) pj_stun_sockaddr_attr_init(pj_stun_sockaddr_attr *attr,
1486
const pj_sockaddr_t *addr,
1490
* Create a generic STUN IP address attribute. The \a addr_len and
1491
* \a addr parameters specify whether the address is IPv4 or IPv4
1494
* @param pool The pool to allocate memory from.
1495
* @param attr_type Attribute type, from #pj_stun_attr_type.
1496
* @param xor_ed If non-zero, the port and address will be XOR-ed
1497
* with magic, to make the XOR-MAPPED-ADDRESS attribute.
1498
* @param addr A pj_sockaddr_in or pj_sockaddr_in6 structure.
1499
* @param addr_len Length of \a addr parameter.
1500
* @param p_attr Pointer to receive the attribute.
1502
* @return PJ_SUCCESS on success or the appropriate error code.
1504
PJ_DECL(pj_status_t) pj_stun_sockaddr_attr_create(pj_pool_t *pool,
1507
const pj_sockaddr_t *addr,
1509
pj_stun_sockaddr_attr **p_attr);
1513
* Create and add generic STUN IP address attribute to a STUN message.
1514
* The \a addr_len and \a addr parameters specify whether the address is
1515
* IPv4 or IPv4 address.
1517
* @param pool The pool to allocate memory from.
1518
* @param msg The STUN message.
1519
* @param attr_type Attribute type, from #pj_stun_attr_type.
1520
* @param xor_ed If non-zero, the port and address will be XOR-ed
1521
* with magic, to make the XOR-MAPPED-ADDRESS attribute.
1522
* @param addr A pj_sockaddr_in or pj_sockaddr_in6 structure.
1523
* @param addr_len Length of \a addr parameter.
1525
* @return PJ_SUCCESS on success or the appropriate error code.
1527
PJ_DECL(pj_status_t) pj_stun_msg_add_sockaddr_attr(pj_pool_t *pool,
1531
const pj_sockaddr_t *addr,
1535
* Initialize a STUN generic string attribute.
1537
* @param attr The string attribute to be initialized.
1538
* @param pool Pool to duplicate the value into the attribute,
1539
* if value is not NULL or empty.
1540
* @param attr_type Attribute type, from #pj_stun_attr_type.
1541
* @param value The string value to be assigned to the attribute.
1543
* @return PJ_SUCCESS on success or the appropriate error code.
1545
PJ_DECL(pj_status_t) pj_stun_string_attr_init(pj_stun_string_attr *attr,
1548
const pj_str_t *value);
1551
* Create a STUN generic string attribute.
1553
* @param pool The pool to allocate memory from.
1554
* @param attr_type Attribute type, from #pj_stun_attr_type.
1555
* @param value The string value to be assigned to the attribute.
1556
* @param p_attr Pointer to receive the attribute.
1558
* @return PJ_SUCCESS on success or the appropriate error code.
1560
PJ_DECL(pj_status_t) pj_stun_string_attr_create(pj_pool_t *pool,
1562
const pj_str_t *value,
1563
pj_stun_string_attr **p_attr);
1566
* Create and add STUN generic string attribute to the message.
1568
* @param pool The pool to allocate memory from.
1569
* @param msg The STUN message.
1570
* @param attr_type Attribute type, from #pj_stun_attr_type.
1571
* @param value The string value to be assigned to the attribute.
1573
* @return PJ_SUCCESS on success or the appropriate error code.
1575
PJ_DECL(pj_status_t) pj_stun_msg_add_string_attr(pj_pool_t *pool,
1578
const pj_str_t *value);
1581
* Create a STUN generic 32bit value attribute.
1583
* @param pool The pool to allocate memory from.
1584
* @param attr_type Attribute type, from #pj_stun_attr_type.
1585
* @param value The 32bit value to be assigned to the attribute.
1586
* @param p_attr Pointer to receive the attribute.
1588
* @return PJ_SUCCESS on success or the appropriate error code.
1590
PJ_DECL(pj_status_t) pj_stun_uint_attr_create(pj_pool_t *pool,
1593
pj_stun_uint_attr **p_attr);
1596
* Create and add STUN generic 32bit value attribute to the message.
1598
* @param pool The pool to allocate memory from.
1599
* @param msg The STUN message
1600
* @param attr_type Attribute type, from #pj_stun_attr_type.
1601
* @param value The 32bit value to be assigned to the attribute.
1603
* @return PJ_SUCCESS on success or the appropriate error code.
1605
PJ_DECL(pj_status_t) pj_stun_msg_add_uint_attr(pj_pool_t *pool,
1612
* Create a STUN generic 64bit value attribute.
1614
* @param pool Pool to allocate memory from.
1615
* @param attr_type Attribute type, from #pj_stun_attr_type.
1616
* @param value Optional value to be assigned.
1617
* @param p_attr Pointer to receive the attribute.
1619
* @return PJ_SUCCESS on success or the appropriate error code.
1621
PJ_DECL(pj_status_t) pj_stun_uint64_attr_create(pj_pool_t *pool,
1623
const pj_timestamp *value,
1624
pj_stun_uint64_attr **p_attr);
1628
* Create and add STUN generic 64bit value attribute to the message.
1630
* @param pool The pool to allocate memory from.
1631
* @param msg The STUN message
1632
* @param attr_type Attribute type, from #pj_stun_attr_type.
1633
* @param value The 64bit value to be assigned to the attribute.
1635
* @return PJ_SUCCESS on success or the appropriate error code.
1637
PJ_DECL(pj_status_t) pj_stun_msg_add_uint64_attr(pj_pool_t *pool,
1640
const pj_timestamp *value);
1643
* Create a STUN MESSAGE-INTEGRITY attribute.
1645
* @param pool The pool to allocate memory from.
1646
* @param p_attr Pointer to receive the attribute.
1648
* @return PJ_SUCCESS on success or the appropriate error code.
1650
PJ_DECL(pj_status_t) pj_stun_msgint_attr_create(pj_pool_t *pool,
1651
pj_stun_msgint_attr **p_attr);
1654
* Create and add STUN MESSAGE-INTEGRITY attribute.
1656
* @param pool The pool to allocate memory from.
1657
* @param msg The STUN message
1659
* @return PJ_SUCCESS on success or the appropriate error code.
1661
PJ_DECL(pj_status_t) pj_stun_msg_add_msgint_attr(pj_pool_t *pool,
1665
* Create a STUN ERROR-CODE attribute.
1667
* @param pool The pool to allocate memory from.
1668
* @param err_code STUN error code.
1669
* @param err_reason Optional STUN error reason. If NULL is given, the
1670
* standard error reason will be given.
1671
* @param p_attr Pointer to receive the attribute.
1673
* @return PJ_SUCCESS on success or the appropriate error code.
1675
PJ_DECL(pj_status_t) pj_stun_errcode_attr_create(pj_pool_t *pool,
1677
const pj_str_t *err_reason,
1678
pj_stun_errcode_attr **p_attr);
1682
* Create and add STUN ERROR-CODE attribute to the message.
1684
* @param pool The pool to allocate memory from.
1685
* @param msg The STUN mesage.
1686
* @param err_code STUN error code.
1687
* @param err_reason Optional STUN error reason. If NULL is given, the
1688
* standard error reason will be given.
1690
* @return PJ_SUCCESS on success or the appropriate error code.
1692
PJ_DECL(pj_status_t) pj_stun_msg_add_errcode_attr(pj_pool_t *pool,
1695
const pj_str_t *err_reason);
1698
* Create instance of STUN UNKNOWN-ATTRIBUTES attribute and copy the
1699
* unknown attribute array to the attribute.
1701
* @param pool The pool to allocate memory from.
1702
* @param attr_cnt Number of attributes in the array (can be zero).
1703
* @param attr Optional array of attributes.
1704
* @param p_attr Pointer to receive the attribute.
1706
* @return PJ_SUCCESS on success or the appropriate error code.
1708
PJ_DECL(pj_status_t) pj_stun_unknown_attr_create(pj_pool_t *pool,
1710
const pj_uint16_t attr[],
1711
pj_stun_unknown_attr **p_attr);
1714
* Create and add STUN UNKNOWN-ATTRIBUTES attribute to the message.
1716
* @param pool The pool to allocate memory from.
1717
* @param msg The STUN message.
1718
* @param attr_cnt Number of attributes in the array (can be zero).
1719
* @param attr Optional array of attribute types.
1721
* @return PJ_SUCCESS on success or the appropriate error code.
1723
PJ_DECL(pj_status_t) pj_stun_msg_add_unknown_attr(pj_pool_t *pool,
1726
const pj_uint16_t attr[]);
1729
* Initialize STUN binary attribute.
1731
* @param attr The attribute to be initialized.
1732
* @param pool Pool to copy data, if the data and length are set.
1733
* @param attr_type The attribute type, from #pj_stun_attr_type.
1734
* @param data Data to be coped to the attribute, or NULL
1735
* if no data to be copied now.
1736
* @param length Length of data, or zero if no data is to be
1739
* @return PJ_SUCCESS on success or the appropriate error code.
1741
PJ_DECL(pj_status_t) pj_stun_binary_attr_init(pj_stun_binary_attr *attr,
1744
const pj_uint8_t *data,
1748
* Create STUN binary attribute.
1750
* @param pool The pool to allocate memory from.
1751
* @param attr_type The attribute type, from #pj_stun_attr_type.
1752
* @param data Data to be coped to the attribute, or NULL
1753
* if no data to be copied now.
1754
* @param length Length of data, or zero if no data is to be
1756
* @param p_attr Pointer to receive the attribute.
1758
* @return PJ_SUCCESS on success or the appropriate error code.
1760
PJ_DECL(pj_status_t) pj_stun_binary_attr_create(pj_pool_t *pool,
1762
const pj_uint8_t *data,
1764
pj_stun_binary_attr **p_attr);
1767
* Create STUN binary attribute and add the attribute to the message.
1769
* @param pool The pool to allocate memory from.
1770
* @param msg The STUN message.
1771
* @param attr_type The attribute type, from #pj_stun_attr_type.
1772
* @param data Data to be coped to the attribute, or NULL
1773
* if no data to be copied now.
1774
* @param length Length of data, or zero if no data is to be
1777
* @return PJ_SUCCESS on success or the appropriate error code.
1779
PJ_DECL(pj_status_t) pj_stun_msg_add_binary_attr(pj_pool_t *pool,
1782
const pj_uint8_t *data,
1786
* Create STUN empty attribute.
1788
* @param pool The pool to allocate memory from.
1789
* @param attr_type The attribute type, from #pj_stun_attr_type.
1790
* @param p_attr Pointer to receive the attribute.
1792
* @return PJ_SUCCESS on success or the appropriate error code.
1794
PJ_DECL(pj_status_t) pj_stun_empty_attr_create(pj_pool_t *pool,
1796
pj_stun_empty_attr **p_attr);
1799
* Create STUN empty attribute and add the attribute to the message.
1801
* @param pool The pool to allocate memory from.
1802
* @param msg The STUN message.
1803
* @param attr_type The attribute type, from #pj_stun_attr_type.
1805
* @return PJ_SUCCESS on success or the appropriate error code.
1807
PJ_DECL(pj_status_t) pj_stun_msg_add_empty_attr(pj_pool_t *pool,
1819
#endif /* __PJNATH_STUN_MSG_H__ */
added
removed
daemon/libs/pjproject-2.0.1/pjnath/include/pjnath/stun_msg.h
