---

TcpLink

---

개요

---

TcpLink 클래스는 UnrealEngine내에서 TCP 소켓을 생성하는 것을 허용합니다. 이 소켓을 통해 인터넷의 다른 서버에 연결하고, 간단한 인터넷 서비스를 제공할 수 있습니다.

이것은 결코 고성능 기능이 아니라는 것에 주의하십시오. 이것을 사용하면, 게임 성능에 심각한 영향을 미칠 수 있습니다. 서비스를 제공할 시, 성능에 미치는 영향은 더 커집니다. 따라서 이 기능을 사용할 때, 이것을 염두해 두셔야 합니다.

이 페이지의 아래쪽에는 TcpLink를 사용하는 몇 가지 예제가 있습니다.

엔진에 포함되어 있는 것이 HTTP WebServer를 구현한 것입니다. 이 웹 서버는 TcpLink 기능을 활용합니다.

모드

---

TcpLink 클래스에는 이 클래스가 작동하는 방법을 제어하는 몇 가지 모드가 있습니다. 이러한 모드들은 아래에서 설명되고 있습니다.

리시브(수신) 모드

수신 시, TcpLink는 다음의 2 가지 모드로 작동할 수 있습니다.

• 이벤트 모드 (RMODE_Event)
• 수동 모드 (RMODE_Manual)

이벤트 모드

이벤트 모드에서 TcpLink 연결의 Native 코드는 링크 모드에 따라 이벤트 중 1개를 트리거합니다.

MODE_Text 에서 ReceivedText 이벤트가 실행됩니다. text 인수는 마지막 이벤트 이후 수신받은 모든 텍스트를 포함합니다.

MODE_Line 에서 ReceivedLine 이벤트가 실행됩니다. line 인수에는 줄 종결자가 없는 1개의 라인이 포함됩니다. 다른 이벤트와 달리 이것은 틱당 1개 이상 발생할 수 있습니다.

MODE_Binary 에서 ReceivedBinary 이벤트가 실행됩니다. count 인수는 바이트 버퍼 B 에 얼마나 많은 바이트가 있는지 나타냅니다.

매뉴얼(수동) 모드

이름이 암시하듯이, 수동 모드에서는 여러분께서 데이터를 읽어야 합니다. 이것은 틱 이벤트 동안 또는 타이머를 사용하여 수행할 수 있습니다. 틱당 여러 개를 읽으면 성능이 느려질 수 있고 작업을 차단할 수 있기에 권장하지 않습니다.

데이터 읽기는 ReadText 또는 ReadBinary 함수를 사용하여 수행할 수 있습니다. 두 함수는 읽은 바이트 수를 반환합니다. ReadBinary 의 count 인수는 읽길 원하는 최대 바이트 수를 정의합니다. 반환 값을 사용하여 실제로 읽을 바이트 수를 결정합니다.

이벤트 모드와 달리 링크 모드가 무엇인지 상관없습니다. 두 함수 중 어느 것을 사용해도 무방합니다. 간략한 IsDataPending 함수를 사용하여 데이터 읽기 자체가 필요한지 여부를 확인하여 보십시오.

링크(연결) 모드

TcpLink가 작동할 수 모드에는 2 가지 각기 다른 모드가 있습니다. 연결 모드는 TcpLink가 리시브 모드인 이벤트 모드에서 작동할 시 어떤 이벤트가 호출되는 가를 결정합니다.

또한, 연결 모드는 SendText 메서드가 어떻게 작동하는가에도 영향을 미칩니다. 연결 모드가 MODE_Line 으로 설정된 경우, SendText 를 사용하여 전송되는 텍스트에 줄바꾸기 종결자가 첨부됩니다. 사용된 줄바꾸기 종결자에 대해서는 라인 모드를 참조해 주십시오.

라인(선) 모드

라인 모드는 텍스트를 받을 때 새로운 라인이 어떻게 감지되는지, 또한 어떤 줄바꾸기 종결자가 SendText 를 사용하여 추가되는지의 방법을 조절합니다. 라인 모드는 링크 모드가 MODE_Line 으로 설정된 경우에만 사용됩니다.

라인 모드는 (OutLineMode)를 전송하는 것과 (InLineMode)를 수신하는 것에 대해 별도로 설정됩니다.

모드	종결자
LMODE_DOS	\n\r
LMODE_UNIX	\n
LMODE_MAC	\r\n	사용되지 말아야 함. 이전 MacOS가 =\r=만을 사용했듯이 올바르지 않음.
LMODE_AUTO	\n\r	수신 시, 이것은 \n=으로 분할하고 =\r 전/후를 삭제함.

링크 스테이트

---

TcpLink에는 현재의 연결 상태를 보고하는 변수인 LinkState 가 포함됩니다. 특히 TcpLink의 이벤트를 사용하는 경우, 일반적으로 이것에 대해 신경쓸 필요는 없습니다. 그러나 일부 경우, 무슨 일이 일어나고 있는지 아는 것이 재미있을지도 모릅니다.

STATE_Initialized

TcpLink의 초기 상태입니다. 연결될 준비가 되어있습니다. _BindPort_를 사용할 수 있습니다.

STATE_Ready

TcpLink 포트에 바운드되어 연결을 설정할 준비가 되어있습니다. Open 또는 Listen 을 사용할 수 있습니다.

STATE_Listening

TcpLink는 incoming 연결을 기다립니다. 이것은 일반적으로 _Listen_으로의 호출의 결과입니다.

STATE_Connecting

연결 시도가 진행 중입니다. 이것은 일반적으로 Open 으로의 호출의 결과입니다. TcpLink는 I/O에 대해 준비가 아직 되어 있지 않습니다.

STATE_Connected

연결이 성립되었고 I/O에 대한 준비가 되어있습니다.

STATE_ListenClosePending

대기 소켓이 닫혀지기를 대기합니다. 이것은 Close 호출의 결과입니다.

STATE_ConnectClosePending

클라이언트 소켓이 닫혀지기를 대기합니다. 이것은 Close 호출의 결과입니다.

STATE_ListenClosing

대기 소켓이 현재 소켓의 연결을 닫고 있습니다. 이것은 아직 어떤 용도로도 사용될 수 없습니다.

STATE_ConnectClosing

클라이언트 소켓이 현재 연결을 닫고 있습니다. 이것은 아직 어떤 용도로도 사용될 수 없습니다.

사용

---

TcpLink 클래스는 클라이언트 또는 서버로의 2가지 다른 방법으로 사용될 수 있습니다.

클라이언트

1. 적절한 모드를 설정합니다.
2. BindPort()
3. IpAddr 구조를 만듭니다. * Resolve (...) 를 사용하여 호스트 이름을 확인합니다. * StringToIpAddr (..) 를 사용하여 IP 문자열을 반환합니다.
4. Open(..)
5. Opened() 이벤트, LinkState 가 STATE_Connected 일 때, 또는 IsConnected() 가 True를 반환하기를 기다립니다.
6. 데이터 읽기 및/또는 쓰기
7. Close(..)

일반적으로 클라이언트는 임의의 사용되지 않는 포트를 사용하기 때문에, BindPort 는 인수 없이 호출되야 합니다.

TcpLink를 클라이언트로 사용하는 방법에 대한 예제는 아래의 패키지에 있는 TcpLinkClient 클래스를 참조해 주십시오.

서버

서버에 대해 TcpLink를 사용하는 것은 좀 더 복잡합니다. 서버를 다음과 같이 2개의 클래스로 분리하는 것을 권장합니다.

1. 일반 대기(listening) 클래스
2. 연결 수락(accepting) 클래스

일반 대기 클래스는 단지 연결 시도를 기다리고, 연결이 되면 연결-수락 클래스를 스폰합니다. 연결-수락 클래스는 실제로 연결을 처리합니다. 이 논리는 TcpLink 클래스에 빌드되기 때문에, AcceptClass 변수를 설정하기만 하면 됩니다.

대기 클래스의 과정은 다음과 같습니다.

1. 적절한 모드를 설정합니다.
2. 대기(listen) 클래스를 설정합니다.
3. BindPort(12345)
4. Listen()
5. [선택 사항] GainedChild(..) 와 LostChild(..) 이벤트에 응답합니다.

서버는 특정 포트에서 대기해야 합니다. 그렇지 않으면, 클라이언트가 어떤 포트에 연결해야 할 지를 모릅니다. 포트가 이미 다른 프로세스에 바운드될 수 있습니다. 이 경우, BindPort(..) 는 0 값을 반환합니다. 이는 즉, 바운드될 포트가 없다는 것을 의미합니다. 다른 방법으로, 2번째 매개 변수를 True로 설정할 수 있습니다. 그럼, 다음 번에 사용 가능한 포트로 바운드합니다. 바운드 포트는 BindPort(..) 호출에 의해 반환됩니다. 바인딩이 성공하면 Listen() 를 호출하여 서버를 시작할 수 있습니다.

AcceptClass 를 정의할 경우, 새 연결이 만들어졌을 때 GainedChild(..) 와 LostChild(..) 이벤트가 호출됩니다. 이것을 사용하여 서버로의 최대 연결 수를 제한할 수 있습니다. 새로운 연결을 수락하는 것을 중지하려면 Close() 를 호출하고, 연결 수락을 다시 시작하려면 Listen()= 을 다시 호출합니다.

연결 수락 클래스는 연결이 수립된 직후의 클라이언트 소켓과 같이 작동합니다.

1. Accepted 이벤트를 기다립니다.
2. 데이터 읽기 및/또는 쓰기
3. Close(..)

AcceptClass 가 설정되어있지 않은 경우, 연결하는 모든 클라이언트에 대해, 대기 클래스는 Accepted 이벤트를 받습니다.

API

---

구조

IpAddr

이것은 IP 주소(IPv4)와 포트 번호의 조합입니다.

변수

LinkMode

링크 모드참조

InLineMode , OutLineMode

링크 모드참조.

Port

로컬 포트.

ReceiveMode

리시브 모드

LinkState

링크 스테이트 참조.

RemoteAddr

다른 쪽 정보를 포함하는 IpAddr 구조입니다.

AcceptClass

서버 모드에서 incoming 연결을 처리하는 클래스로 사용됩니다.

여기에 나열되어 있는 것 이외에 다른 변수가 있지만 그러한 것들은 내부적으로 사용되는 것이므로 수정되지 말아야 합니다.

함수

IsDataPending

native function bool IsDataPending()

소켓에서 데이터가 pending 중인 경우, True를 반환합니다.

ParseURL

native function bool ParseURL(coerce string URL, out string Addr, out int PortNum, out string LevelName, out string EntryName)

Unreal URL을 구문 분석합니다. 유효한 URL에 대해 True를 반환합니다. Unreal URL은 브라우저에서 익숙한 URL과는 다릅니다. 그다지 유용하지 않을지도 모릅니다.

Resolve

native function Resolve( coerce string Domain )

제공된 호스트 이름을 첫 번째 인수로 처리합니다. 호스트 이름 확인은 시간이 걸리는 과정이기 때문에 함수의 결과는 이벤트를 통해 반환됩니다.

확인이 성공하면 Resolved 가 호출됩니다. 그렇지 않으면, ResolveFailed 이벤트가 호출됩니다.

GetLastError

native function int GetLastError()

마지막 오류 코드를 반환합니다. 0 반환 값은 오류가 없다는 것을 의미합니다. 다른 값이 무엇을 의미하는지 언더레이 하위 시스템에 달려있습니다. MS Windows의 경우, 오류 코드 WinSock API와 동일합니다.

IpAddrToString

native function string IpAddrToString( IpAddr Arg )

IpAddr 구조를 문자열로 변환합니다. 예: 123.123.123.123:45678

StringToIpAddr

native function bool StringToIpAddr( string Str, out IpAddr Addr )

IPv4 주소와 포트를 IpAddr 구조로 구문 분석합니다. 성공하면 True를 반환합니다.

GetLocalIP

native function GetLocalIP(out IpAddr Arg )

로컬 IP 주소를 가져옵니다. 이것은 언더레이 하위 시스템에 의해 반환되는 첫 번째 IP 주소로 라우팅 가능한 주소가 아닐 수도 있습니다. 그러므로,주의하여 사용하십시오.

BindPort

native function int BindPort( optional int PortNum, optional bool bUseNextAvailable )

이 TcpLink 인스턴스에 대한 포트에 연결합니다. 포트 번호가 주어지지 않은 경우, 임의의 사용되지 않는 포트를 할당합니다. 2 번째 인수가 True이면, 이미 원하는 포트가 사용된 경우 다음 사용 가능한 사용하지 않는 포트가 바인딩됩니다. False이면 바인딩은 단순히 실패합니다.

반환값이 바운드 포트이고, 실패한 경우에는 0입니다.

Listen

native function bool Listen()

TcpLink를 대기 모드로 설정합니다. 성공하면 True를 반환합니다. 대기 모드에서 TcpLink는 incoming 연결을 기다립니다. 자세한 내용은 서버 모드를 참조해 주십시오.

Open

native function bool Open( IpAddr Addr )

원격 호스트로의 연결을 엽니다. StringToIpAddr 또는 Resolve 를 사용하여 유효한 IpAddr 구조를 가져옵니다.

연결 초기화에 문제가 있을 경우 False를 반환합니다. 이 함수를 호출한 후, 소켓은 아직 통신할 준비가 되어 있지 않습니다. Opened 이벤트를 기다리거나 IsConnected 가 True가 될 때까지를 기다립니다.

Close

native function bool Close()

현재 연결을 닫습니다. TcpLink가 incoming 연결에 대해 대기하는 것을 중지시키거나 또는 원격 호스트에 대한 연결을 닫으려면 이것을 사용합니다. 연결을 닫은 후, Open 또는 Close 를 사용하여 다시 열 수 있습니다.

IsConnected

native function bool IsConnected()

TcpLink가 원격 호스트에 연결되어 있으면 True를 반환합니다. 클라이언트 모드에서 사용할 수 있는 연결이 원격 호스트로 수립되면 True를 반환합니다. 서버 모드에서는 클라이언트가 연결된 경우에만 True를 반환합니다.

SendText

native function int SendText( coerce string Str )

원격 호스트에 문자열을 보냅니다. 링크 모드가 MODE_Line 이 경우, 라인 종결자가 추가됩니다. 자세한 내용은 라인 모드를 참조해 주십시오.

원격 호스트로 보내진 바이트 수를 반환합니다. 이것은 문자열의 길이와 다를지도 모릅니다.

SendBinary

native function int SendBinary( int Count, byte B[255] )

원격 호스트에 바이트의 수를 보냅니다. count 인수는 원격 호스트로 보낼 버퍼의 바이트 수(2 번째 인수)를 정의합니다. 한 번에 보낼 수 있는 최대 바이트 수는 255 바이트입니다.

원격 호스트에 전송할 바이트 수를 반환합니다.

ReadText

native function int ReadText( out string Str )

원격 호스트에서 텍스트를 읽습니다. 이것은 차단하는 작업이므로 데이터를 읽을 때까지 반환되지 않습니다. 이 함수는 매뉴얼 모드에서만 사용되야 합니다.

이것은 읽은 바이트 수를 반환합니다. 이것은 문자열의 길이와 동일 필요는 없습니다.

ReadBinary

native function int ReadBinary( int Count, out byte B[255] )

원격 호스트에서 count 바이트를 읽습니다. 한 번에 읽을 수 있는 바이트는 255 바이트입니다. 이 함수는 매뉴얼 모드에서만 사용되야 합니다.

이것은 읽은 바이트 수를 반환합니다. 이것은 count 에서 제공되는 값보다 적을 수 있습니다.

이벤트

Resolved

event Resolved( IpAddr Addr )

호스트 이름 확인에 성공하면 호출됩니다.

ResolveFailed

event ResolveFailed()

호스트 이름이 확인되지 않은 경우에 호출됩니다.

Accepted

event Accepted()

클라이언트가 대기 모드의 TcpLink에 연결하거나, 또는 대기 모드의 TcpLink 의해 스폰된 TcpLink에 연결할 경우 호출됩니다.

Opened

event Opened()

성공한 open 명령의 결과로 TcpLink에 대해 호출됩니다.

Closed

event Closed()

TcpLink 연결이 닫힐 때 호출됩니다. 이것은 호출된 close 의 결과 또는 원격 호스트가 연결을 닫을 시의 결과일 수 있습니다.

ReceivedText

event ReceivedText( string Text )

링크 모드가 MODE_Text 이고 리시브 모드가 RMODE_Event 인 경우 TcpLink가 텍스트를 받을 때 호출됩니다.

ReceivedLine

event ReceivedText( string Line )

링크 모드가 MODE_Line 이고 리시브 모드가 RMODE_Event 인 경우 TcpLink가 텍스트를 받을 때 호출됩니다. 링크 모드에 따라 텍스트가 줄바꾸기(newlines)에서 제거됩니다. 이 이벤트는 틱당 여러 번 호출될 수 있습니다.

ReceivedText

event ReceivedBinary( int Count, byte B[255] )

링크 모드가 MODE_Binary 이고 리시브 모드가 RMODE_Event 인 경우 TcpLink가 텍스트를 받을 때 호출됩니다. count 인수는 바이트 버퍼에 얼마나 많은 바이트가 기록되었는 가를 정의합니다.

예제

---

zip 파일에 포함된 것은 TcpLink 클래스 사용의 몇 가지 예제입니다.

TcpLinkClient

매우 간단한 HTTP 클라이언트입니다.

TcpLinkServer

수신 받는 모든 라인에 에코하는 간단한 서버입니다. 이 과정은 실제 TcpLinkServerAcceptor 클래스에 의해 처리됩니다.

TcpLinkServerAcceptor

TcpLinkServer 이 수신하는 연결을 처리하는 클래스입니다.

• TcpLinkExamples.zip: TcpLink 예제