PJNATH - TURN 세션 모듈

출처 : http://purematter.blog.me/110102478757

TURN 세션 사용하기

Creating the session

세션을 생성하기 위해 pj_turn_session_create()를 사용합니다.

Configuring credential

모든 TURN operations들은 인증을 필요로 합니다. 세션에서 사용할 TURN credential은 pj_turn_session_set_credential()을 사용합니다.

Configuring server

어플리케이션은 Allocate request를 전송하기 전에 반드시 pj_turn_session_set_server()를 호출해야 합니다. 이 함수는 resolver가 설정되어 있다면 DNS SRV resolution 사용하여 TURN server를 해석합니다. 서버의 해석은 비동기적으로 완수될 것이며, 어플리케이션은 PJ_TURN_STATE_RESOLVERD의 상태 값과 함께pj_turn_session_cb의 on_state() 를 통해 결과를 통보 받을 것입니다.

Creating allocation

pj_turn_session_alloc()을 사용해서 하나의 “relay port”를 TURN server에 생성하십시오. 이 함수는 allocate request를 서버로 전송할 것입니다. 이 함수는 즉시 완료될 것이고, 어플리케이션은 pj_turn_session_cb의 on_state() 를 통해 할당의 결과를 통보 받을 것입니다.

Getting the allocation result

allocation이 성공했다면, session의 상태는 PJ_TURN_STATE_READY 로 진행될 것이며, 그렇지 않다면 상태는 PJ_TURN_STATE_DEALLOCATED나 더 높은 값으로 바뀔 것입니다. session 상태 전이는 pj_turn_session_cb 구조체의 on_state() 콜백을 통해 보고될 것입니다. allocation이 성공한 상태에서, 어플리케이션은 pj_turn_session_get_info()를 호출해서 allocation 정보를 가져올 수 있습니다.

Sending data through the relay

allocation이 한번 생성되면, 클라이언트는 “relay port”를 사용해서 어떠한 remote endpoints(peer)로도 데이터를 전송할 수 있습니다. peer 주소를 제공하여 pj_turn_session_sendto()를 호출하면 됩니다. 그러나 이 시점에서, peer에게 권한을 부여하기 전에 “relay port”를 통해 클라이언트에게 데이터를 전송하는 것은 허용되지 않습니다.

Creating permissions

peer가 “relay port”를 통해 데이터를 전송하기 위해서는 TURN server에 권한을 생성할 필요가 있습니다. 이것이 없다면, TURN server가 “relay port”를 통해 peer로 부터 데이터를 수신하면 즉시 버립니다. 인자에 peer의 IP address를 포함하는 pj_turn_session_set_perm()을 호출하여 권한을 생성하십시오.

Receiving data from peers

peer에게 권한이 부여되면, TURN server의 “relay port”를 통해 수신된 어떠한 데이터도 클라이언트에게 중계됩니다. 어플리케이션은 pj_turn_session_cb의 on_rx_data를 통해 통보받습니다.

Using ChannelData

TURN은 ChannelData packetization을 사용하여 데이터에 대한 최적화된 틀framing을 제공합니다. 클라이언트는 pj_turn_session_bind_channel()을 호출하여 이러한 포맷이 활성화되도록 할 수 있습니다. peer로 송수신되는 데이터는 Send/Data Indication을 사용하는 대신 ChannelData 포맷을 사용하게 됩니다.

Refeshing the allocation, permissions, and channel bindings

Allocations, permissions와 channel bindings는 클라이언트에 의해 주기적으로 갱신될 필요가 있습니다. 그렇지 않으면 만료expired될 것입니다.

Destroying the allocation

더 이상 “relay port”가 필요하지 않으면, 클라이언트는 pj_turn_session_shutdown()을 호출하여allocation을 제거할 수 있습니다. 이 함수는 즉시 리턴하게 되며, 어플리케이션은 pj_turn_session_cb 구조체의 on_state() 콜백을 통해 그 결과를 통보 받게 됩니다. session의 상태가 PJ_TURN_STATE_DESTROYING에 도달하면, 어플리케이션은 해당 session이 조만간 제거될 것이라고 가정해야 합니다.

Data Structures

struct pj_turn_channel_data
struct pj_turn_session_cb
struct pj_turn_alloc_param
struct pj_turn_session_info

Enumeration Type Documentation

enum pj_turn_state_t

PJ_TURN_STATE_NULL		TURN session 이 생성된 직후의 상태.
PJ_TURN_STATE_RESOLVING		TURN server가 설정되었고 이제 DNS SRV 해석이 진행되고 있는 상태.
PJ_TURN_STATE_RESOLVED		TURN server 해석(resolved)되었습니다. 만약 처리되야 할 대기할당(pending allocation)이 있다면 즉시 처리됩니다.
PJ_TURN_STATE_ALLOCATING		TURN session이 ALLOCATE request를 요청했고TURN server로부터 응답을 기다리고 있는 상태.
PJ_TURN_STATE_READY		TURN session이 중계 리소스를 성공적으로 할당했고 사용할 준비가 된 상태.
PJ_TURN_STATE_DEALLOCATING		TURN session이 할당 해제 요청을 했고 TURN server로부터 응답을 기다리고 있는 상태.
PJ_TURN_STATE_DEALLOCATED		할당 해제 응답이 수신되었습니다. session은 보통 DESTROYING 상태로 이동하기 위한 처리를 시작합니다.
PJ_TURN_STATE_DESTROYING		TURN session이 제거되고 있는 상태.

enum pj_turn_tp_type

TURN 전송 타입입니다. 두 곳에서 사용되는데, TURN server와 통신타입을 지정할 때와 allocation transport의 타입(REQUESTED-TRANSPORT attribute)을 지정할 때입니다.

PJ_TURN_TP_UDP	UDP transport, 이 값은 IANA protocol number입니다.
PJ_TURN_TP_TCP	TCP transport, 이 값은 IANA protocol number입니다.
PJ_TURN_TP_TLS	TLS transport. The TLS transport will only be used as the connection type to reach the server and never as the allocation transport type.

Functions

void pj_turn_alloc_param_default (pj_turn_alloc_param *prm)

디폴트값으로 pj_turn_alloc_param을 초기화합니다.

Parameters:

prm 초기화할 TURN allocation 파라미터.

void pj_turn_alloc_param_copy (pj_pool_t *pool, pj_turn_alloc_param *dst, const pj_turn_alloc_param *src)

pj_turn_alloc_param 을 복제합니다.

Parameters:

pool (현재는 사용되지 않습니다).

dst Destination parameter.

src Source parameter.

const char * pj_turn_state_name (pj_turn_state_t state)

TURN 상태를 문자열 표현으로 리턴합니다.

Parameters:

state TURN session 상태

Returns:

NULL로 끝나는 상태 이름의 문자열

pj_status_t pj_turn_session_create (const pj_stun_config *cfg, const char *name, int af, pj_turn_tp_type conn_type, const pj_turn_session_cb *cb, unsigned options, void *user_data, pj_turn_session **p_sess)

지정된 주소 패밀리와 커넥션 타입으로 TURN session 인스턴스를 생성합니다. TURN session 인스턴스가 생성되면, 어플리케이션은 TURN server에 릴레이주소를 할당하기 위해 pj_turn_session_alloc()을 호출해야 합니다.

Parameters:

cfg STUN 설정

name 로그에서 확인하기 위해 지정하는 세션의 이름

af 클라이언트 커넥션의 address family. 현재 pj_AF_INET()와 pj_AF_INET6()이 지원됩니다.

conn_type TURN server와의 커넥션 타입

cb TURN session으로 부터 이벤트를 수신할 콜백

options 현재는 반드시 0을 지정해야 합니다.

user_data 임의의 어플리케이션 데이터

p_sess 생성된 TURN session을 가리킬 포인터

Returns:

성공시에는 PJ_SUCCESS, 실패시에는 적당한 에러코드가 리턴됩니다.

pj_status_t pj_turn_session_shutdown (pj_turn_session *sess)

TURN client session을 종료합니다. client session 오브젝트를 정상적으로 제거합니다.

Parameters:

sess TURN client session.

Returns:

성공시에는 PJ_SUCCESS, 실패시에는 적당한 에러코드가 리턴됩니다.

pj_status_t pj_turn_session_destroy (pj_turn_session *sess)

TURN session을 강제적으로 제거합니다. 세션을 즉시 제거합니다. 만약 사용중인 allocation이 있다면, 서버는 제거되는 클라이언트에 대한 정보를 통보받지 못합니다.

Parameters:

sess TURN client session.

Returns:

성공시에는 PJ_SUCCESS, 실패시에는 적당한 에러코드가 리턴됩니다.

pj_status_t pj_turn_session_get_info (pj_turn_session *sess, pj_turn_session_info *info)

TURN session과 allocation에 대한 정보를 가져옵니다.

Parameters:

sess TURN client session.

info TURN session 정보로 초기화될 구조체

Returns:

성공시에는 PJ_SUCCESS, 실패시에는 적당한 에러코드가 리턴됩니다.

pj_status_t pj_turn_session_set_user_data (pj_turn_session *sess, void *user_data)

유저 데이터와 TURN session을 연관시킵니다. 유저데이터는 나중에 pj_turn_session_get_user_data()를 통해 가져올 수 있습니다.

Parameters:

sess TURN client session.

user_data 임의의 데이터

Returns:

성공시에는 PJ_SUCCESS, 실패시에는 적당한 에러코드가 리턴됩니다.

void * pj_turn_session_get_user_data (pj_turn_session *sess)

이전에 TURN session에 연관시킨 유저 데이터를 가져옵니다.

Parameters:

sess TURN client session.

Returns:

user/application data.

void pj_turn_session_set_log (pj_turn_session *sess, unsigned flags)

메시지 로깅을 설정합니다. 기본적으로 모든 플래그가 활성화됩니다.

Parameters:

sess TURN client session.

flags pj_stun_sess_msg_log_flag 의 비트 마스크 조합

pj_status_t pj_turn_session_set_software_name (pj_turn_session *sess, const pj_str_t *sw)

TURN session에 의해 보내지는 모든 STUN request들에 저장할 SOFTWARE 이름을 설정합니다.

Parameters:

sess TURN client session.

sw 소프트웨어 이름 문자열. NULL이면, 세션은 STUN 요청과 응답메시지에 SOFTWARE attribute를 포함시키지 않습니다.

Returns:

성공시에는 PJ_SUCCESS, 실패시에는 적당한 에러코드가 리턴됩니다.

pj_status_t pj_turn_session_set_server (pj_turn_session *sess, const pj_str_t *domain, int default_port, pj_dns_resolver *resolver)

서버나 서버의 도메인네임을 설정합니다. 어플리케이션이 Allocate request를 보낼 수 있게 되기 전에, 이 함수를 사용하여 반드시 서버의 주소를 resolveing해야 합니다. 이 함수는 리졸버resolver가 설정되어 있다면 DNS SRV resolution을 사용하여 TURN server를 해석합니다. 서버 이름 해석과정은 비동기적으로 완료되며, 어플리케이션은 PJ_TURN_STATE_RESOLVED 상태와 함께 on_state()를 통해 통보받습니다.

어플리케이션은 서버 이름 해석이 완료되기 전에 pj_turn_session_alloc()을 호출할 수 있습니다. 이 경우에, 그 작업은 session에 큐queue되고, 서버 이름 해석이 완료되면 보내집니다.

Parameters:

sess TURN client session.

domain TURN server의 도메인, 호스트네임, IP 주소. 이 인자가 도메인 이름을 포함하고 있다면, 리졸버(resolver) 인자가 반드시 지정되어야 합니다. 그래야 DNS SRV 해석을 실행할 수 있기 때문입니다.

default_port DNS SRV 해석이 사용되지 않을 경우에 사용할 디폴트 TURN port. DNS SRV 해석이 사용될 경우, 서버 포트는 DNS SRV 레코드로부터 얻습니다.

resolver 이것이 NULL이 아니면, domain 인자가 우선적으로 해석되고, DNS SRV 해석이 실패할때 DNS A/AAAA 해석을 사용하여 대비합니다. NULL이면, domain 인자는 호스트네임으로 해석됩니다.

Returns:

작업이 성공적으로 입력되면 PJ_SUCCESS, 그렇지 않으면 적당한 에러코드. 이 함수가 PJ_SUCCESS를 리턴하면, 해석 작업의 최종 결과는 on_state() 콜백을 통해 통보됩니다.

pj_status_t pj_turn_session_set_credential (pj_turn_session *sess, const pj_stun_auth_cred *cred)

TURN server에서 인증할 때 사용될 자격정보credential을 설정합니다. 어플리케이션은 pj_turn_session_alloc()를 통해 Allocate request를 보내기 전에 반드시 이 함수를 호출해야 합니다.

Parameters:

sess The TURN client session

cred 사용될 STUN credential.

Returns:

성공시에는 PJ_SUCCESS, 실패시에는 적당한 에러 코드.

pj_status_t pj_turn_session_alloc (pj_turn_session *sess, const pj_turn_alloc_param *param)

TURN Allocate request를 보내서 relay address와 리소스를 TURN server상에 할당합니다. 이 함수를 호출하기 전에 어플리케이션은 우선 pj_turn_session_set_server()를 호출하여 서버 이름 해석 과정을 시작해야 하고 pj_turn_session_set_credential()로 자격정보credential(인증정보)를 설정해야 합니다. 이 함수는 비동기적으로 완료되고, 어플리케이션은 on_state() callback을 통해 할당의 결과를 통보 받습니다. allocation이 성공하면 TURN session 상태는 PJ_TURN_STATE_READY로 전환하고, 실패하면 PJ_TURN_STATE_DEALLOCATING 나 그 이상으로 전환합니다. 할당이 한번 성공하게 되면 TURN session은 자신이 제거되기 전까지 주기적인 allocation 갱신(refresh)을 서버로 전송하여 이 allocation을 살아있게(keep-alive) 합니다.

Parameters:

sess TURN client session.

param TURN allocation 파라미터 옵션.

Returns:

성공시에는 PJ_SUCCESS, 실패시에는 적당한 에러 코드.

pj_status_t pj_turn_session_set_perm (pj_turn_session *sess, unsigned addr_cnt, const pj_sockaddr addr[], unsigned options)

지정된 peer IP addresses들에 대해 TURN server에 권한permission을 생성하거나 갱신합니다. 어플리케이션은 지정된 IP address로 데이터를 전송하기 전에 특정 (peer) IP address에 권한을 부여해야 하며 그렇지 않을 경우 TURN server는 그 데이터를 버립니다.

Parameters:

sess TURN client session.

addr_cnt IP 주소 갯수.

addr peer IP 주소 배열. 소켓의 address family와 IP 주소 부분만이 중요합니다.

options 권한(permission)이 만료되기전에 TURN session에서 그것을 자동적으로 갱신하게 하려면 1을 지정하십시오.

Returns:

성공시에는 PJ_SUCCESS, 실패시에는 적당한 에러 코드. 이 함수는 비동기 함수입니다.

pj_status_t pj_turn_session_sendto (pj_turn_session *sess, const pj_uint8_t *pkt, unsigned pkt_len, const pj_sockaddr_t *peer_addr, unsigned addr_len)

TURN relay를 통해 지정된 peer address로 데이터를 전송합니다. 이 함수는 데이터를 STUN Send Indication이나 TURN ChannelData 패킷으로 포장해서 TURN server로 전송합니다. TURN server는 그 데이터를 다시 peer에게 전송합니다.

allocation은 어플리케이션이 데이터를 전송할 수 있게 되기 전까지 성공적으로 생성되어 있어야 합니다.

TURN session은 전송 계층에 독립적이기 때문에, 이 함수는 최종적으로 on_send_pkt() callback을 호출하여어플리케이션이 실제로 패킷을 TURN server로 전송하도록 합니다.

Parameters:

sess TURN client session.

pkt peer에게 전송할 데이터, 패킷

pkt_len 데이터의 길이

peer_addr 원격 피어(peer)의 주소 (최종적인 데이터의 목적지입니다. TURN server의 주소가 아닙니다).

addr_len 주소의 길이

Returns:

성공시에는 PJ_SUCCESS, 실패시에는 적당한 에러 코드.

pj_status_t pj_turn_session_bind_channel (pj_turn_session *sess, const pj_sockaddr_t *peer, unsigned addr_len)

지정된 peer address에 추가적으로 channel binding을 만듭니다. 이 함수는 주어진 peer address에 유일한 channel number를 할당하고 TURN server에 이 주소에 대한 channel binding을 요청합니다. peer에 channel이 바인딩되면, TURN client와 TURN server는 ChannelData encapsulation format을 사용해서 데이터를 교환할 것이고, 이것은 Send Indication 보다 낮은 대역폭을 차지합니다.

이 함수는 비동기적으로 완료되며, 어플리케이션은 on_channel_bound() callback을 통해 결과를 통보 받을 것입니다.

Parameters:

sess TURN client session.

peer 원격 피어 주소

addr_len 주소의 길이

Returns:

성공시에는 PJ_SUCCESS, 실패시에는 적당한 에러 코드.

pj_status_t pj_turn_session_on_rx_pkt (pj_turn_session *sess, void *pkt, pj_size_t pkt_len, pj_size_t *parsed_len)

서버로부터 패킷을 수신을 TURN client session에 통보합니다. TURN session은 transport에 독립적이기 때문에, 소켓으로부터 패킷을 읽지 않고, TURN server부터 수신된 패킷을 전달하는 어플리케이션에 의존합니다. 그러면 session은 이 패킷을 처리하고 그것이 TURN protocol 교환인지 유저에게 전달해야 할 데이터인지 결정합니다. 유저의 데이터라면 on_rx_data() callback을 호출할 것입니다.

Parameters:

sess TURN client session.

pkt TURN server로부터 수신한 패킷. 이것은 STUN으로 포장된 메시지이거나 ChannelData 패킷입니다.

pkt_len 패킷의 길이

parsed_len 패킷으로부터, 처리되거나 파싱된 만큼의 길이

Returns:

비 STUN, 비 ChannelData 패킷이 수신되었거나 on_rx_data()가 에러를 리턴한다면, 이 함수는 PJ_SUCCESS가 아닌 값을 리턴할 것입니다.