PJNATH - TURN 전송 모듈

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

TURN transport 사용하기

이 오브젝트는 TURN client session에 대한 얇은 래퍼를 제공합니다. 따라서 TURN client session과 매우 유사한 API를 제공합니다.

Typedef

typedef struct pj_turn_sock pj_turn_sock

Functions

void pj_turn_sock_cfg_default (pj_turn_sock_cfg *cfg)

pj_turn_sock_cfg 구조체를 디폴트값으로 설정합니다.

pj_status_t pj_turn_sock_create (pj_stun_config *cfg, int af, pj_turn_tp_type conn_type, const pj_turn_sock_cb *cb, const pj_turn_sock_cfg *setting, void *user_data, pj_turn_sock **p_turn_sock)

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

Parameters:

cfg 이 transport의 작업에서 사용할 ioqueue와 timer heap 인스턴스를 포함한 STUN 설정.

af 소켓의 address family. 현재는 pj_AF_INET() 과 pj_AF_INET6() 이 지원됩니다.

conn_type TURN sever로의 커넥션 타입. TCP나 UDP가 지원됩니다.

cb TURN transport로부터 이벤트를 수신받기 위한 콜백

setting 이 transport에 지정할 추가 설정. 이것이 NULL이면 기본값이 사용됩니다.

user_data 이 transport에 연관될 임의의 유저 데이터

p_turn_sock 생성된 TURN transport 인스턴스를 가리키는 포인터

Returns:

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

void pj_turn_sock_destroy (pj_turn_sock *turn_sock)

TURN transport 인스턴스를 제거합니다. 클라이언트와 TURN server 간의 커넥션을 우아하게 종료합니다. 이 함수는 즉시 리턴 할 것이지만, TURN socket의 제거는 백그라운드에서 계속되고 어플리케이션은 이 transport로 부터 상태 변화 통보를 여전히 받게 됩니다.

Parameters:

turn_sock TURN transport 인스턴스.

pj_status_t pj_turn_sock_set_user_data (pj_turn_sock *turn_sock, void *user_data)

유저 데이터와 TURN transport를 연관시킵니다. 유저 데이터는 이 후에 pj_turn_sock_get_user_data()를 통해 가져올 수 있습니다.

Parameters:

turn_sock TURN transport 인스턴스.

user_data 임의의 데이터.

Returns:

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

void * pj_turn_sock_get_user_data (pj_turn_sock *turn_sock)

이전에 TURN transport에 할당되었던 유저 데이터를 가져옵니다.

Parameters:

turn_sock TURN transport 인스턴스.

Returns:

유저/어플리케이션 데이터

pj_status_t pj_turn_sock_get_info (pj_turn_sock *turn_sock, pj_turn_session_info *info)

TURN transport 정보를 가져옵니다. transport info는, 무엇보다도, 할당된 relay address를 포함하게 됩니다.

Parameters:

turn_sock TURN transport 인스턴스.

info TURN transport 정보로 채워질 구조체.

Returns:

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

pj_status_t pj_turn_sock_lock (pj_turn_sock *turn_sock)

TURN transport의 내부 뮤텍스를 획득합니다. 어플리케이션은 TURN transport와 함께 다른 오브젝트들에 대한 접근을 동기화하기 위해 이 함수를 호출해야 합니다.

Parameters:

turn_sock TURN transport 인스턴스.

Returns:

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

pj_status_t pj_turn_sock_unlock (pj_turn_sock *turn_sock)

pj_turn_sock_lock()으로 묶여있던 내부 뮤텍스를 해방시킵니다.

Parameters:

turn_sock TURN transport 인스턴스.

Returns:

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

void pj_turn_sock_set_log (pj_turn_sock *turn_sock, unsigned flags)

이 TURN session에 대한 STUN message 로깅을 설정합니다.

Parameters:

turn_sock TURN transport 인스턴스.

flags pj_stun_sess_msg_log_flag의 비트 마스크 조합.

pj_status_t pj_turn_sock_set_software_name (pj_turn_sock *turn_sock, const pj_str_t *sw)

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

Parameters:

turn_sock TURN transport instance.

sw 소프트웨어 이름 문자열. NULL이 지정되거나 비어있다면, 세션은 STUN request와 response에 SOFTWARE attribute를 포함시키지 않습니다.

Returns:

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

pj_status_t pj_turn_sock_alloc (pj_turn_sock *turn_sock, const pj_str_t *domain, int default_port, pj_dns_resolver *resolver, const pj_stun_auth_cred *cred, const pj_turn_alloc_param *param)

relay address와 리소스를 TURN server에 할당합니다. 이 함수는 DNS SRV를 사용하여 서버 이름 해석 과정을 시작하고 지정된 자격정보credential를 사용하여 TURN Allocate request를 전송합니다. 이 함수는 비동기적으로 완료되고, 어플리케이션은 on_state() callback을 통해 할당의 결과를 통보 받습니다. allocation이 성공하면 TURN session 상태는 PJ_TURN_STATE_READY로 이동합니다. 실패하면 PJ_TURN_STATE_DEALLOCATING 나 그 이상으로 이동합니다.

Parameters:

turn_sock TURN transport instance.

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 인자는 호스트네임으로 해석됩니다.

cred TURN server에 사용될 STUN credention.

param 추가적인 TURN allocation parameter.

Returns:

이 작업이 성공적으로 입력되면 PJ_SUCCESS, 실패하면 적당한 에러 코드. 이 함수가 PJ_SUCCESS를 리턴할때, allocation process의 최종 결과는 on_state() 콜백을 통해 어플리케이션에 통보될 것입니다.

pj_status_t pj_turn_sock_set_perm (pj_turn_sock *turn_sock, unsigned addr_cnt, const pj_sockaddr addr[], unsigned options)

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

Parameters:

turn_sock TURN transport 인스턴스.

addr_cnt IP 주소의 갯수.

addr IP 주소의 배열.

options TURN client session이 자동적으로 권한을 갱신하게 하려면 1을 지정하십시오.

Returns:

작업이 성공적으로 호출되면 PJ_SUCCESS, 실패시에는 적당한 에러 코드. 이 함수는 비동기 함수입니다.

pj_status_t pj_turn_sock_sendto (pj_turn_sock *turn_sock, 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은 어플리케이션이 데이터를 전송할 수 있게 되기 전까지 성공적으로 생성되어 있어야 합니다.

Parameters:

turn_sock The TURN transport instance.

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

pkt_len 데이터의 길이

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

addr_len 주소의 길이

Returns:

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

pj_status_t pj_turn_sock_bind_channel (pj_turn_sock *turn_sock, 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 보다 낮은 대역폭을 차지합니다. (Send Indication은 peer address가 channel에 바운딩되어 있지 않을 경우에 사용되는 디폴트 전송 포맷입니다)

Parameters:

turn_sock The TURN transport 인스턴스.

peer remote peer address.

addr_len address의 길이.

Returns:

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