사용자 API 함수

본 장에서는 사용자 usrmain() 프로그램에서 사용할 수 있는 API 함수를 설명한다.

1. Callback 함수

1.1. user_thrmain

사용자가 작성해야 할 스레드 메인 Callback 함수이다. TCPGWTHR는 사용자가 작성한 프로그램을 스레드 형태로 수행한다.

  • 프로토타입

    int user_thrmain(WORKTHRINFO *wthrinfo, int server)

  • 파라미터

    파라미터 설명

    wthrinfo

    스레드에서 넘겨준 WORKTHRINFO에 대한 포인터이다.

    server

    해당 스레드가 서버 모드인지 아니면 클라이언트 모드인지를 나타내는 변수이다.

    • 0 : 클라이언트 모드

    • 1 : 서버 모드

  • 반환값

    반환값에 사용되는 매크로는 tcphdr.h 헤더 파일에 정의되어 있다.

    반환값 설명

    WTHR_NORMAL_RETURN

    해당 스레드가 정상적으로 완료된 경우이다. 에러 로그 없이 서버 또는 클라이언트와의 연결을 정상적으로 종료한다.

    WTHR_ABNORMAL_RETURN

    해당 스레드가 비정상적으로 종료된 경우이다. 에러 로그가 slog에 기록되며 연결을 종료한다.

2. API 함수

다음은 API 함수의 목록이다. 함수의 프로토타입은 tcphdr.h 헤더 파일에 정의되어 있다.

함수명 설명

tcpgw_tpcall

Tmax 서비스 동기식 호출 함수이다.

tcpgw_tpacall

Tmax 서비스 비동기 호출 함수이다.

tcpgw_tpreply

Tmax에 결과를 반환하기 위한 함수이다.

tcpgw_get_svcdata

Tmax에서 오는 데이터를 받기 위한 함수이다.

tcpgw_select

해당 스레드에 요청을 받을 때까지 정해진 시간만큼 대기하는 함수이다.

tcpgw_network_connect

TCPGWTHR가 클라이언트 모드로 동작할 경우 리모트와 연결하기 위한 함수이다.

tcpgw_read

리모트로부터 데이터를 수신하는 함수이다.

tcpgw_write

리모트에 데이터를 전송하는 함수이다.

tcpgw_portno_ipaddr

리모트의 주소와 포트 번호를 얻는 함수이다.

tcpgw_client_id

스레드에 할당된 게이트웨이 환경 파일에 입력한 ID를 얻어 오는 함수이다.

tcpgw_getaddr_from_winfo

스레드에서 넘겨준 WORKTHRINFO 구조체로부터 리모트의 주소와 포트 번호를 얻는 함수이다.

2.1. tcpgw_tpcall

Tmax 서비스 동기식 호출 함수이다.

  • 프로토타입

    int tcpgw_tpcall(WORKTHRINFO *wthrinfo, char *svc, char *ptr, long alen,
                 char *optr, long *olen)

  • 파라미터

    파라미터 설명

    wthrinfo

    스레드에서 넘겨준 WORKTHRINFO에 대한 포인터이다.

    svc

    Tmax 서비스명이다.

    ptr

    Tmax 서비스에 전달할 데이터가 저장된 버퍼 포인터이다.

    alen

    Tmax 서비스에 전달할 데이터 길이이다.

    optr

    Tmax 서비스에서 처리 결과를 받을 버퍼 포인터이다.

    olen

    처리 결과의 데이터 길이가 저장될 long 포인터이다.

  • 반환값

    Tmax 서비스를 처리할 때 오류가 발생하면 반환값으로 오류 코드가 반환된다. 반환값이 –1인 경우에는 비정상적인 오류가 발생한 경우이다. 그 외의 minus 값은 Tmax에서 서비스를 처리할 때 오류가 발생한 경우 오류 코드이다(부호를 제외한 실제 에러 코드값).

2.2. tcpgw_tpacall

Tmax 서비스 비동기 호출 함수이다. 단, 요청만 가능하며 결과는 받아올 수 없다(TPNOREPLY).

  • 프로토타입

    int tcpgw_tpacall(WORKTHRINFO *wthrinfo, char *svc, char *ptr, long alen)

  • 파라미터

    파라미터 설명

    wthrinfo

    스레드에서 넘겨준 WORKTHRINFO에 대한 포인터이다.

    svc

    Tmax 서비스명이다.

    ptr

    Tmax 서비스에 전달할 데이터가 저장된 버퍼 포인터이다.

    alen

    Tmax 서비스에 전달할 데이터 길이이다.

  • 반환값

    Tmax 서비스를 처리할 때 오류가 발생하면 반환값으로 오류 코드가 반환된다. 반환값이 –1인 경우에는 비정상적인 오류가 발생한 경우이다. 그 외의 minus 값은 Tmax에서 서비스를 처리할 때 오류가 발생한 경우의 오류 코드이다(부호를 제외한 실제 에러 코드값).

2.3. tcpgw_tpreply

Tmax에 결과를 반환하기 위한 함수이다. Tmax에서 서비스 요청이 먼저 온 경우 리모트에서 서비스를 처리하고 그 결과를 Tmax에 전달한다.

  • 프로토타입

    int tcpgw_tpreply(WORKTHRINFO *wthrinfo, char *ptr, long alen, int err)

  • 파라미터

    파라미터 설명

    wthrinfo

    스레드에서 넘겨준 WORKTHRINFO에 대한 포인터이다.

    ptr

    Tmax 서비스에 전달할 데이터가 저장된 버퍼 포인터이다.

    alen

    Tmax 서비스에 전달할 데이터 길이이다.

    err

    서비스를 처리할 때 오류가 발생할 경우 오류 코드이다.

  • 반환값

    Tmax 서비스를 처리할 때 오류가 발생하면 반환값으로 오류 코드가 반환된다. 반환값이 –1인 경우에는 비정상적인 오류가 발생한 경우이다. 그 외의 minus 값은 Tmax에서 서비스를 처리할 때 오류가 발생한 경우의 오류 코드이다(부호를 제외한 실제 에러 코드값).

2.4. tcpgw_get_svcdata

Tmax에서 전달되는 데이터를 받기 위한 함수이다.

  • 프로토타입

    int tcpgw_get_svcdata(WORKTHRINFO *wthrinfo, char *ptr, int *err, int *flags)

  • 파라미터

    파라미터 설명

    wthrinfo

    스레드에서 넘겨준 WORKTHRINFO에 대한 포인터이다.

    ptr

    데이터가 저장될 버퍼이다.

    err

    오류 코드가 저장될 int 포인터이다.

    flags

    Tmax에서 서비스를 요청할 때 응답을 받을 것인지 아닌지를 저장한다.

    0이면 Tmax 서비스에서 응답을 기다리는 상태이고, 1이면 응답을 기다리지 않는 상태이다.

  • 반환값

    반환값 설명

    데이터 길이

    함수 호출에 성공한 경우이다.

    –1

    함수 호출에 실패한 경우이다.

2.5. tcpgw_select

해당 스레드에 요청을 받을 때까지 정해진 시간만큼 대기하는 함수이다.

  • 프로토타입

    int tcpgw_select(WORKTHRINFO *wthrinfo, int sec, int usec)

  • 파라미터

    파라미터 설명

    wthrinfo

    스레드에서 넘겨준 WORKTHRINFO에 대한 포인터이다.

    sec

    타임아웃이다. (단위: 초)

    usec

    타임아웃이다. (단위: 백만분의 1초)

  • 반환값

    반환값 설명

    WTHR_SELECT_TIMEOUT(1)

    타임아웃일 경우이다.

    WTHR_TMAX_REQUEST(2)

    Tmax 요청일 경우이다.

    WTHR_USER_REQUEST(3)

    리모트 요청일 경우이다.

    WTHR_SELECT_ERROR(-1)

    그 외 에러인 경우이다.

2.6. tcpgw_network_connect

TCPGWTHR가 클라이언트 모드로 동작할 경우 리모트와 연결하기 위한 함수이다.

  • 프로토타입

    int tcpgw_network_connect(char *host, int port, int sec)

  • 파라미터

    파라미터 설명

    host

    리모트와 연결할 주소나 리모트 hostname이다. IPv6 주소를 지원한다.

    port

    리모트와 연결할 포트 번호이다.

    sec

    타임아웃이다. (단위: 초)

  • 반환값

    반환값 설명

    소켓 번호

    함수 호출에 성공한 경우이다.

    –1

    함수 호출에 실패한 경우이다.

2.7. tcpgw_read

리모트로부터 데이터를 수신하는 함수이다.

  • 프로토타입

    int tcpgw_read(int fd, char *ptr, int nbytes, int sec, int usec)

  • 파라미터

    파라미터 설명

    fd

    리모트 소켓 번호이다.

    ptr

    데이터가 저장된 버퍼 포인터이다.

    nbytes

    리모트로 수신할 데이터 길이이다.

    sec

    타임아웃이다. (단위: 초)

    usec

    타임아웃이다. (단위: 백만분의 1초)

  • 반환값

    반환값 설명

    데이터 길이

    함수 호출에 성공한 경우이다.

    –1

    함수 호출에 실패한 경우이다.

2.8. tcpgw_write

리모트에 데이터를 전송하는 함수이다.

  • 프로토타입

    int tcpgw_write(int fd, char *ptr, int nbytes)

  • 파라미터

    파라미터 설명

    fd

    리모트 소켓 번호이다.

    ptr

    데이터가 저장된 버퍼 포인터이다.

    nbytes

    리모트로 수신할 데이터 길이이다.

  • 반환값

    반환값 설명

    데이터 길이

    함수 호출에 성공한 경우이다.

    –1

    함수 호출에 실패한 경우이다.

2.9. tcpgw_portno_ipaddr

리모트의 주소와 포트 번호를 얻는 함수이다.

  • 프로토타입

    int tcpgw_portno_ipaddr(char *ipaddr)

  • 파라미터

    파라미터 설명

    ipaddr

    리모트 주소가 저장될 버퍼이다.

  • 반환값

    환경설정에 지정된 리모트 포트 번호가 반환된다.

2.10. tcpgw_client_id

스레드에 할당된 게이트웨이 환경 파일에 입력한 ID를 얻어 오는 함수이다.

  • 프로토타입

    int tcpgw_client_id (WORKTHRINFO *wthrinfo, char *id)

  • 파라미터

    파라미터 설명

    wthrinfo

    스레드에서 넘겨준 WORKTHRINFO에 대한 포인터이다.

    id

    ID가 저장될 버퍼이다.

  • 반환값

    사용되지 않는다.

2.11. tcpgw_getaddr_from_winfo

스레드에서 넘겨준 WORKTHRINFO 구조체로부터 리모트의 주소와 포트 번호를 얻는 함수이다.

  • 프로토타입

    int tcpgw_getaddr_from_winfo(WORKTHRINFO *wthrinfo, char *ipaddr)

  • 파라미터

    파라미터 설명

    wthrinfo

    스레드에서 넘겨준 WORKTHRINFO에 대한 포인터이다.

    ipaddr

    리모트 주소가 저장될 버퍼이다. IPv6 주소를 설정한 경우에는 버퍼의 크기를 충분히 할당해야 한다.

  • 반환값

    환경설정에 지정된 리모트 포트 번호가 반환된다.