PJLib - APIs

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

void pj_activesock_cfg_default(pj_activesock_cfg * cfg)

기본값으로 active socket 설정을 초기화합니다.

Parameters:

cfg 초기화될 설정을 저장한 구조체

pj_status_t pj_activesock_close(pj_activesock_t * asock)

active socket을 종료합니다. socket을 ioqueue로부터 등록해제하고 socket을 닫습니다.

Parameters:

asock 액티브소켓

Returns:

성공하면 PJ_SUCCESS가 리턴되며, 실패면 적당한 에러코드가 리턴됩니다.

pj_status_t pj_activesock_create (pj_pool_t * pool, pj_sock_t sock, int sock_type, const pj_activesock_cfg * opt, pj_ioqueue_t * ioqueue, const pj_activesock_cb * cb, void * user_data, pj_activesock_t ** p_asock)

지정된 소켓으로 액티브 소켓을 만듭니다. 이 함수는 소켓을 지정된 ioqueue에 등록하게 됩니다.

Parameters:

pool 할당할 메모리를 가져오는 풀
sock 소켓 핸들
sock_type 소켓 타입입니다. pj_SOCK_DGRAM() 나 pj_SOCK_STREAM() 입니다. 액티브 소켓은 연결 기반 소켓을 위한 커넥션 클로져를 다루기 위한 정보를 필요로 합니다.
ioqueue 사용할 ioqueue
opt 선택적인 설정들. 이 설정이 지정되지 않을 때는, 기본값이 사용됩니다.
cb 어플리케이션 콜백callback이 포함된 구조체 포인터
user_data 액티브 소켓에 연관 지을 임의의 유저 데이터
p_asock 액티스 소켓 인스턴스를 넘겨받을 포인터

Returns:

성공하면 PJ_SUCCESS가 리턴되며, 실패할 때는 적당한 에러코드가 리턴됩니다.

pj_status_t pj_activesock_create_udp (pj_pool_t * pool, const pj_sockaddr * addr, const pj_activesock_cfg * opt, pj_ioqueue_t * ioqueue, const pj_activesock_cb * cb, void * user_data, pj_activesock_t ** p_asock, pj_sockaddr * bound_addr)

UDP 소켓 디스크립터를 생성하고, 지정하는 주소에 바인딩하고, 액티브 소켓을 만듭니다.

Parameters:

pool 할당할 메모리를 가져오는 풀
addr 주소 패밀리address family와 소켓이 바인드bind되어야 할 주소를 지정합니다. 이 인자가NULL이면, AF_INET으로 간주되고 소켓은 어떤 주소와 포트로도 바인드bind될 수 있습니다.
opt 선택적인 설정입니다. 지정되지 않으면, 기본값이 사용됩니다.
cb 어플리케이션 콜백callback이 포함된 구조체 포인터
user_data 액티브 소켓에 연관 지을 임의의 유저 데이터
p_asock 액티스 소켓 인스턴스를 넘겨받을 포인터
bound_addr 이 인자가 지정되면, 리턴시 바인드bind된 주소로 채워집니다.

Returns:

성공하면 PJ_SUCCESS가 리턴되며, 실패할 때는 적당한 에러코드가 리턴됩니다.

void * pj_activesock_get_user_data (pj_activesock_t * asock)

액티브 소켓과 연관된 유저 데이터를 가져옵니다.

Parameters:

asock 액티브 소켓

Returns:

유저 데이터

pj_status_t pj_activesock_send ( pj_activesock_t * asock,pj_ioqueue_op_key_t * send_key, const void * data, pj_ssize_t * size, unsigned flags)

소켓을 사용해서 데이터를 전송합니다.

Parameters:

asock 액티브 소켓
send_key 데이터를 전송하기 위한 operation key입니다. 이것은 어플리케이션이 multiple pending send operation을 수행하고 on_data_sent() callback에서 전송한 데이터를 추적하기를 원할 때 유용합니다.
data 전송할 데이터. 이 데이터는 전송되어 질 때까지 유효한 상태로 남아있어야 합니다.
size 데이터의 크기
flags pj_ioqueue_send()에 전달할 플래그

Returns:

데이터가 즉시 전송되었다면 PJ_SUCCESS, 그렇지 않다면 PJ_EPENDING을 리턴합니다. 데이터가 실제로 전송되었을 때 on_data_sent() 콜백callback이 호출될 것입니다. 그 외의 다른 리턴값은 에러를 뜻합니다.

pj_status_t pj_activesock_sendto(pj_activesock_t * asock, pj_ioqueue_op_key_t * send_key, const void * data, pj_ssize_t * size, unsigned flags, const pj_sockaddr_t * addr, int addr_len)

소켓을 사용해서 데이터그램을 전송합니다.

Parameters:

asock 액티브 소켓
send_key 데이터를 전송하기 위한 operation key입니다. 이것은 어플리케이션이 multiple pending send operation을 수행하고 on_data_sent() callback에서 전송한 데이터를 추적하기를 원할 때 유용합니다.
data 전송할 데이터. 이 데이터는 전송되어 질 때까지 유효한 상태로 남아있어야 합니다.
size 데이터의 크기.
flags pj_ioqueue_send()에 전달할 플래그.
addr 목적지 주소.
addr_len 목적지 주소의 길이.

Returns:

데이터가 즉시 전송되었다면 PJ_SUCCESS, 그렇지 않다면 PJ_EPENDING을 리턴합니다. 데이터가 실제로 전송되었을 때 on_data_sent() 콜백callback이 호출될 것입니다. 그 외의 다른 리턴값은 에러를 뜻합니다.

pj_status_t pj_activesock_set_user_data(pj_activesock_t * asock, void * user_data)

액티브 소켓과 임의의 데이터를 연관시킵니다. 어플리케이션은 콜백에서 이 데이터를 조회하고 더 높은 레벨의 처리에 연관할 수 있습니다.

Parameters:

asock 액티브 소켓
user_data 액티브 소켓과 연관된 유저 데이터

Returns:

작업 성공 시 PJ_SUCCESS, 그렇지 않으면 적당한 에러코드를 리턴합니다.

pj_status_t pj_activesock_start_accept (pj_activesock_t * asock, pj_pool_t * pool)

액티브소켓상에서 비동기 accept() 작업을 시작합니다. 어플리케이션은 이 함수를 호출하기 전에 bind해야 합니다. 이 함수는 async_cnt 만큼의 비동기 accept() 작업을 호출하고 호출자에게로 리턴합니다. socket상의 Incoming connectioin은 on_accept_complete() callback을 통해 어플리케이션으로 콜백됩니다.

어플리케이션 accept() 작업을 시작하기 위해 오직 한번만 이 함수를 호출해야 합니다. 추가적인 accept() 작업은 on_accept_complete() 콜백callback이 0이 아닌 값을 리턴 할 때 액티브소켓에 의해 자동적으로 수행될 것입니다.

Parameters:

asock 액티브 소켓.
pool 내부 데이터를 할당하기 위해 사용하는 메모리 풀

Returns:

작업 성공 시 PJ_SUCCESS, 그렇지 않으면 적당한 에러코드를 리턴합니다.

pj_status_t pj_activesock_start_connect(pj_activesock_t * asock, pj_pool_t * pool, const pj_sockaddr_t * remaddr, int addr_len)

비동기 소켓 connect() 작업을 수행합니다. 연결이 완료되면, on_connect_complete() 콜백이 호출될 것입니다.

Parameters:

asock 액티브 소켓.
pool 내부 데이터를 할당하기 위해 사용하는 메모리 풀
remaddr 원격 주소
addr_len 원격 주소의 길이

Returns:

연결이 즉시 완료되면 PJ_SUCCESS, 그렇지 않다면 PJ_EPENDING을 리턴합니다. 연결이 완료되면 on_connect_complete() 콜백이 호출될 것입니다. 그 외의 다른 리턴값은 에러를 뜻합니다.

pj_status_t pj_activesock_start_read(pj_activesock_t * asock, pj_pool_t * pool, unsigned buff_size, pj_uint32_t flags)

액티브소켓상에 read 작업을 시작합니다. 이 함수는 buff_size 길이 만큼의 버퍼를 async_cnt 개 만큼 생성합니다. 버퍼들은 지정된 풀pool로부터 할당됩니다. 한번 버퍼가 생성되면, async_cnt 개 만큼의 비동기 recv() 작업을 호출하고 호출자에게로 리턴합니다. 소켓으로 들어오는 데이터는 on_data_read() 콜백callback을 통해 어플리케이션으로 보고됩니다.

어플리케이션은 read 작업을 수행하기 위해 이 함수를 오직 한번만 호출하면 됩니다. 추가적인 read 작업은 on_data_read() 콜백callback이 0이 아닌 값을 리턴 할 때 액티브소켓에 의해 자동적으로 수행됩니다.

Parameters:

asock 액티브 소켓.
pool 수신데이터를 할당하기 위해 사용하는 메모리 풀.
buff_size 각 버퍼의 크기.
flags pj_ioqueue_recv() 에 주어질 플래그.

Returns:

작업 성공 시 PJ_SUCCESS, 그렇지 않으면 적당한 에러코드를 리턴합니다.

pj_status_t pj_activesock_start_read2 ( pj_activesock_t * asock, pj_pool_t * pool, unsigned buff_size, void * readbuf[], pj_uint32_t flags)

액티브소켓에서 버퍼를 할당하지 않도록 어플리케이션에서 read 작업에 대한 버퍼를 제공한다는 것을 제외하면, pj_activesock_start_read()와 동일합니다.

Parameters:

asock 액티브 소켓.
pool 수신데이터를 할당하기 위해 사용하는 메모리 풀.
buff_size 각 버퍼의 크기.
readbuf 패킷버퍼의 배열, 각 크기는 buff_size 크기.
flags pj_ioqueue_recv() 에 주어질 플래그.

Returns:

작업 성공 시 PJ_SUCCESS, 그렇지 않으면 적당한 에러코드를 리턴합니다.

pj_status_t pj_activesock_start_recvfrom(pj_activesock_t * asock, pj_pool_t * pool, unsigned buff_size, pj_uint32_t flags)

이 함수는 데이터그램 소켓에서만 사용되고, on_data_recvfrom() 콜백callback이 대신 호출된다는 점 이외에는 pj_activesock_start_read()와 동일합니다.

Parameters:

asock 액티브 소켓.
pool 수신데이터를 할당하기 위해 사용하는 메모리 풀.
buff_size 각 버퍼의 크기.
readbuf 패킷버퍼의 배열, 각 크기는 buff_size 크기.
flags pj_ioqueue_ recvfrom () 에 주어질 플래그.

Returns:

작업 성공 시 PJ_SUCCESS, 그렇지 않으면 적당한 에러코드를 리턴합니다.

pj_status_t pj_activesock_start_recvfrom2(pj_activesock_t * sock, pj_pool_t * pool, unsigned buff_size, void * readbuf[], pj_uint32_t flags)

recvfrom() 작업이 버퍼를 새로 만드는 대신 인자로 받는다는 것을 제외하면 pj_activesock_start_recvfrom()와 같습니다.

Parameters:

asock 액티브 소켓.
pool 수신데이터를 할당하기 위해 사용하는 메모리 풀.
buff_size 각 버퍼의 크기.
readbuf 패킷버퍼의 배열, 각 크기는 buff_size 크기.
flags pj_ioqueue_ recvfrom () 에 주어질 플래그.

Returns:

작업 성공 시 PJ_SUCCESS, 그렇지 않으면 적당한 에러코드를 리턴합니다.