클라이언트 플러그인¶

Important

FunapiNetwork 는 deprecated 될 예정입니다. 이 페이지는 기존에 FunapiNetwork를 사용하시는 분들을 위한 도움말입니다.

FunapiNetwork 클래스¶

서버와의 통신을 시작하려면 먼저 FunapiNetwork 객체를 생성해야 합니다.

public FunapiNetwork (bool session_reliability = false)

Session 이란 서버에 접속하면 부여되는 개인의 고유 ID 같은 것입니다. 서버에 접속할 때마다 매번 새로운 ID가 발급되고 통신할 때 서버에서는 이 세션 값으로 유저를 구분하게됩니다. 이 값은 Transport 상관 없이 FunapiNetwork 하나 당 하나씩 발급됩니다. FunapiNetwork 객체를 여러 개 사용한다면 각각의 FunapiNetwork는 서로 다른 세션 ID를 갖게 됩니다.

Session Reliability 란 서버와의 통신이 끊겨도 재연결시 동일한 세션으로 계속해서 통신할 수 있도록 해주는 기능입니다. 동일한 세션으로 계속 통신할 수 있다는 것의 의미는 서버에 처음 접속 후 거쳐야 하는 인증 및 초기화 과정을 생략할 수 있고 서버에서도 유저의 데이터 값을 그대로 유지할 수 있다는 뜻입니다. 모바일처럼 접속이 자주 끊길 수 있는 환경에서는 이 세션 값을 유지하는 것이 꽤 중요한 이슈가 됩니다. 이 옵션 값이 true 일 경우 서버와의 연결이 끊겨도 재연결시 기존의 세션 ID로 통신이 가능하고 메시지의 시퀀스 값을 비교해서 메시지를 동기화하는 작업도 하게 됩니다. 이전 연결에서 미처 보내지 못 한 메시지가 있다면 이 과정에서 서버로 전송하게 됩니다. 현재 Session reliability 기능은 TCP 프로토콜에서만 사용할 수 있습니다.

그 외에 FunapiNetwork 를 초기화할 때 설정할 수 있는 값과 콜백함수들이 있습니다. 아래는 초기화 과정에서 설정할 수 있는 값입니다.

SequenceNumberValidation	TCP, HTTP 프로토콜로 메시지를 보낼 때 sequence number 를 함께 보냄
ResponseTimeout	서버에서 아무런 응답이 없을 때 연결을 끊기까지 대기하는 시간

SequenceNumberValidation 기본값은 false 로 되어 있으며 true 로 설정할 경우 session reliability 옵션과 상관없이 메시지를 보낼 때 sequence number 도 함께 보내게 됩니다. 이 기능을 사용하면 서버에서 패킷의 유효성을 검증할 수 있고 잘못된 패킷을 보내는 유저를 막을 수 있습니다.

ResponseTimeout 기본값은 0 으로 되어 있으며 0 일 때는 아무런 동작도 하지 않습니다. 0 이상의 값으로 설정할 경우 해당 시간 이내에 서버로부터 아무런 메시지를 받지 못하면 연결을 끊고 종료 콜백을 호출합니다. ResponseTimeout 은 사용하고 싶지만 구현상 그렇게 자주 패킷이 오고 가지 않을 경우 Ping 을 사용해서 서버로부터 주기적으로 응답을 받을 수 있습니다.

플러그인에서 사용하는 콜백들은 유니티의 event 객체를 사용하고 있습니다. 이벤트로 콜백을 등록하는 방법은 아래와 같이 ‘+=’ 연산자를 사용합니다. 하나의 이벤트에 여러개의 콜백을 등록할 수 있습니다.

// 서버로부터 세션 ID를 받으면 OnSessionInitCallback 함수가 호출됩니다.
network.OnSessionInitiated += OnSessionInitCallback;

FunapiNetwork의 콜백 함수는 아래와 같습니다.

OnSessionInitiated	세션의 초기화가 완료되면 호출되는 함수
OnSessionClosed	세션이 종료되면 호출되는 함수
TransportConnectFailedCallback	Transport의 연결 시도가 실패하면 호출되는 함수
TransportDisconnectedCallback	Transport의 소켓 연결이 끊기면 호출되는 함수
StoppedAllTransportCallback	모든 Transport의 연결이 종료되면 호출되는 함수

OnSessionInitiated 이 콜백 함수가 호출된 시점을 서버와 메시지를 주고 받는 것의 시작 시점으로 보면 됩니다. 이 콜백이 불리면 서버와 연결이 된 후에 세션 아이디까지 전달 받은 직후이기 때문입니다. 서버와 메시지를 주고 받을 때 세션 아이디를 함께 전달하게 되는데 세션 아이디를 받기 전에 보내는 메시지는 버려지게 됩니다. session reliability 옵션을 사용하면 메시지를 버리지 않고 큐에 쌓아두지만 실제로 보내지는 않습니다. 이렇게 큐에 쌓인 메시지는 서버로부터 세션 아이디를 받은 직후 전송됩니다.

OnSessionClosed 세션이 종료되면 호출되는 함수입니다. 연결이 끊겼다고 무조건 세션이 종료되는 것은 아니고 FunapiNetwork.Stop(true) 함수를 호출해서 연결을 종료하거나 서버에서 해당 세션을 닫았거나 서버에서 세션 아이디를 다른 걸 보냈을 경우 이 콜백 함수가 호출됩니다. FunapiNetwork.Stop 함수를 호출할 때 파라미터를 false 로 주거나 물리적인 네트워크 환경으로 인해 연결이 종료되었을 때는 OnSessionClosed 콜백 함수가 호출되지 않습니다. 서버로부터 새 세션 아이디를 받았을 경우에는 OnSessionClosed 콜백 함수가 호출된 후 새로운 세션 아이디와 함께 OnSessionInitiated 콜백 함수가 호출됩니다.

StoppedAllTransportCallback 이 콜백 함수가 호출된 시점을 서버와의 연결이 모두 종료된 시점으로 보면 됩니다. 만약 FunapiNetwork 에 여러개의 Transport 를 등록해서 사용하고 있다면 하나의 연결만 끊겼을 때는 이 콜백이 호출되지 않습니다. 그 때에는 FunapiTransport 클래스의 StoppedCallback 의 호출 시점을 연결이 끊긴 시점으로 보는 것이 좋습니다.

FunapiTransport 클래스¶

서버와의 메시지 전송, 수신 등의 역할을 담당하는 객체입니다. 프로토콜에 따라 세 종류의 클래스가 있습니다. FunapiTcpTransport, FunapiUdpTransport, FunapiHttpTransport 중 사용할 프로토콜의 객체를 생성해서 FunapiNetwork 객체에 AttachTransport 하면 됩니다.

// encoding : 메시지 타입. FunEncoding.kProtobuf 또는 FunEncoding.kJson
FunapiTransport transport = new FunapiTcpTransport(ip, port, encoding);
network.AttachTransport(transport);

하나의 FunapiNetwork에 여러 개의 Transport를 등록할 수 있지만 같은 타입의 Transport를 중복해서 등록할 수는 없습니다. 만약 같은 프로토콜 타입의 Transport를 여러 개 사용하고 싶다면 지금은 FuanpiNetwork를 여러 개 생성해서 따로 관리해야 합니다. 이 부분은 추후 개선될 예정에 있지만 정확한 시기는 아직 미정입니다.

FunapiTransport 를 초기화할 때 설정할 수 있는 값과 콜백 함수는 아래와 같습니다.

ConnectTimeout

float

연결 대기 시간 (초)

ConnectTimeout 연결이 지연될 경우 대기하는 시간입니다. 지정된 시간 안에 연결이 되지 않으면 ConnectTimeoutCallback 함수가 호출됩니다.

// 10초 이상 연결이 지연될 경우 OnConnectTimeout 함수가 호출됩니다.
transport.ConnectTimeout = 10f;
transport.ConnectTimeoutCallback += OnConnectTimeout;

StartedEventHandler	서버와의 연결이 완료되면 호출되는 함수
StoppedEventHandler	서버와의 연결이 종료되면 호출되는 함수
FailureCallback	Transport에 오류가 발생하면 호출되는 함수
ConnectTimeoutHandler	ConnectTimeout 시간 내에 서버와 연결이 되지 않으면 호출되는 함수

FailureCallback 는 Transport 내에서 오류가 발생했을 때 호출되는 콜백 함수입니다. 오류가 발생했을 때 FunapiTransport.LastErrorCode 와 FunapiTransport.LastErrorMessage 를 사용해서 해당 오류에 대한 자세한 정보를 확인할 수 있습니다.

ConnectTimeoutHandler 는 서버와의 연결시간이 초과되었을 때 호출되는 이벤트 콜백 함수입니다. 정해진 시간 내에 연결이 되지 않으면 ConnectTimeoutCallback 함수가 호출됩니다. 타임아웃 시간 값은 ConnectTimeout 변수에 할당하면 됩니다.

FunapiTcpTransport¶

TCP Transport 에서 사용 가능한 property 입니다.

AutoReconnect	bool	연결에 실패했을 때 재연결을 시도할 지 여부
DisableNagle	bool	Nagle 알고리즘 사용 여부
EnablePing	bool	클라이언트 핑 사용 여부

AutoReconnect 연결에 실패했을 때 재연결을 시도할지 여부를 결정합니다. 재연결 시도는 exponential time 간격으로 재접속을 시도합니다. (1초, 2초, 4초, 8초,… 간격으로 재시도)

DisableNagle 네이글 알고리즘을 사용할지 여부를 결정합니다. 기본 값은 false 로 되어 있어서 기본적으로 네이글 알고리즘을 사용하고 있습니다. 사용하고 싶지 않다면 이 값을 true 로 설정하면 됩니다.

EnablePing 클라이언트에서 핑을 사용할지 여부를 결정합니다. EnablePing 값은 연결이 되기 전에만 값을 설정할 수 있고 연결이 된 후에는 값을 변경해도 반영이 되지 않습니다.

FunapiHttpTransport¶

HTTP Transport 에서 사용 가능한 property 입니다.

UseWWW	bool	UnityEngine 의 WWW 클래스를 사용할지 여부
RequestTimeout	float	요청에 대한 timeout 시간

UseWWW FunapiHttpTransport 에서 HTTP 요청을 처리할 때 HttpWebRequest 클래스를 사용하고 있습니다. 그런데 Windows 버전의 Unity Editor 에서 HttpWebRequest 클래스를 사용하면 간혹 Unity Editor 가 블러킹되는 현상이 있어 UnityEngine 의 WWW 클래스를 사용할 수 있도록 이 옵션이 추가되었습니다. 에디터에서만 발생하는 현상이므로 기본적으로는 이 옵션을 false 로 두고 에디터에서 실행할 때만 WWW 클래스를 사용하는 것을 권장합니다.

RequestTimeout HTTP 요청에 대한 timeout 시간을 지정할 수 있습니다. 기본값은 30초로 되어 있습니다. 지정된 시간 내에 요청에 대한 응답을 받지 못하면 요청이 취소되고 FailureCallback 함수가 호출됩니다.

기본 프로토콜¶

하나의 FunapiNetwork 에는 여러 개의 FunapiTransport를 등록할 수 있는데 메시지를 주고 받을 때 특정 프로토콜을 지정하지 않으면 기본 프로토콜로 메시지를 주고 받게 됩니다. 기본 프로토콜은 여러 개의 Transport를 등록할 때 처음 등록되는 Transport의 프로토콜을 기본 프로토콜로 정하게 됩니다.

기본 프로토콜은 변경이 가능하며 SetDefaultProtocol 함수를 통해 변경할 수 있습니다. 물론 FunapiNetwork에 하나의 Transport만 등록해서 사용한다면 이 부분은 신경쓰지 않아도 됩니다.

// FunapiNetwork에 등록된 프로토콜 중 하나를 지정해서 기본 프로토콜로 정할 수 있습니다.
// 만약 등록되지 않은 프로토콜을 지정할 경우 오류가 발생할 수 있으니 주의해 주세요.
public void SetDefaultProtocol (TransportProtocol protocol)

예제¶

FunapiNetwork 객체를 생성하고 TCP Transport 객체를 생성해서 FunapiNetwork 에 등록하고 연결을 시도해보는 샘플 코드입니다. 이 코드는 플러그인 샘플 코드인 TestNetwork.cs 파일과 FunapinetworkTest.cs 파일에서도 확인할 수 있습니다.

// FunapiNetwork 객체를 생성합니다. session reliability 기능 사용.
FunapiNetwork network = new FunapiNetwork(session_reliability);

// FunapiNetwork 콜백들을 등록해줍니다.
network.OnSessionInitiated += OnSessionInitiated;
network.OnSessionClosed += OnSessionClosed;
network.MaintenanceCallback += OnMaintenanceMessage;
network.StoppedAllTransportCallback += OnStoppedAllTransport;
network.TransportConnectFailedCallback += OnTransportConnectFailed;
network.TransportDisconnectedCallback += OnTransportDisconnected;

// ResponseTimeout 을 사용하면 서버에서 해당 시간 이상 응답이 없을 경우 서버와의 연결을 종료합니다.
// 기본값은 0으로 되어 있고 값을 지정하지 않으면 해당 기능은 동작하지 않습니다.
// 모바일 환경에서는 연결이 자주 끊길 수 있어서 이 기능을 사용하는 것을 권장합니다.
// 서버와 그렇게 자주 패킷을 주고 받지 않는다면 Ping 기능을 함께 사용하는 것이 좋습니다.
network.ResponseTimeout = 10f;

// "echo" 메시지에 대한 핸들러를 등록합니다.
// 메시지마다 핸들러 함수를 등록해야 메시지의 응답을 받을 수 있습니다.
network.RegisterHandler("echo", this.OnEcho);

// TCP Transport 객체를 json 타입으로 생성합니다.
FunapiTcpTransport transport = new FunapiTcpTransport("127.0.0.1", 8012, FunEncoding.kJson);

// 연결에 실패했을 경우 4번 정도까지 exponential time 간격으로 재접속을 시도합니다.
transport.AutoReconnect = true;

// Ping을 사용합니다. 이 기능은 TCP에서만 사용할 수 있습니다.
transport.EnablePing = true;

// FunapiTransport 콜백들을 등록해줍니다.
transport.StartedCallback += OnTransportStarted;
transport.StoppedCallback += OnTransportClosed;
transport.FailureCallback += OnTransportFailure;

// 연결을 기다리는 시간을 설정할 수 있습니다.
// 10 초 이내에 연결이 되지 않을 경우 OnConnectTimeout 함수가 호출됩니다.
transport.ConnectTimeoutCallback += OnConnectTimeout;
transport.ConnectTimeout = 10f;

// FunapiNetwork에 Transport를 추가합니다.
// DetachTransport 함수를 통해 삭제도 가능합니다.
network.AttachTransport(transport);

// 서버와의 연결을 시작합니다.
// Transport가 여러 개 등록되어 있다면 모든 Transport의 연결을 동시에 시도합니다.
network.Start();

ResponseTimeout 기능을 사용해서 서버와의 연결이 끊겼다고 판단하고 플러그인이 연결을 끊으면 가장 마지막에 호출되는 콜백이 StoppedAllTransportCallback 함수입니다. 연결이 끊겼을 경우 이 함수에서 재연결을 시도하는 것이 적절한데 이 함수는 정상적으로 종료할 때도 호출되기 때문에 이 점을 유의해서 구현하시기 바랍니다. 추후 Response Timeout 으로 인해 연결이 끊겼을 때 호출되는 콜백이 추가될 예정입니다.

메시지 전송 및 수신¶

메시지 타입¶

메시지 타입은 Json 과 Protocol buffer 두 가지 타입을 사용할 수 있습니다. FunapiTransport 객체를 생성할 때 해당 Transport가 어떤 타입의 인코딩을 사용할지 파라미터로 전달해야 합니다. 파라미터의 형태는 아래와 같습니다.

// Message encoding type
public enum FunEncoding
{
    kJson,        // JSON
    kProtobuf     // Protobuf-net
}

핸들러 등록¶

메시지를 전송하고 그에 대한 응답 메시지를 받았을 때 처리를 위한 메시지 핸들러를 등록해야 합니다. 메시지 핸들러는 메시지 타입과 콜백함수만 등록하는 방법이 있고 프로토콜을 함께 지정해서 등록할 수도 있습니다. 서버로부터 메시지를 받았을 때 기본 프로토콜로 지정된 Transport의 인코딩 타입으로 메시지를 디코딩하게 됩니다.

만약 하나의 FunapiNetwork에 서로 다른 인코딩 타입의 Transport를 2개 이상 등록했다면 Default protocol의 인코딩 타입이 아닌 메시지일 경우 메시지 핸들러를 등록할 때 프로토콜 타입을 함께 지정해야 합니다.

핸들러 등록은 RegisterHandler 함수를 통해서 하며 핸들러 함수의 원형은 아래와 같습니다.

// 핸들러 함수 원형. 같은 형태의 함수를 만들어 원하는 메시지의 핸들러로 등록하면 된다.
public delegate void MessageHandler(string msg_type, object body);

// 핸들러 등록 함수
// Default protocol의 인코딩 타입으로 메시지를 받게 됩니다.
public void RegisterHandler(string type, MessageHandler handler);

// 프로토콜을 지정하는 핸들러 등록 함수
// 지정된 프로토콜의 인코딩 타입으로 메시지를 받게 됩니다.
public void RegisterHandlerWithProtocol(string type, TransportProtocol protocol, MessageEventHandler handler)

type	메시지 이름입니다. 반드시 서버에 정의된 메시지 필드와 동일한 이름으로 등록해야 합니다.
handler	해당 메시지를 수신하면 호출되는 콜백 함수입니다.
msg_type	수신한 메시지 이름입니다.
body	수신한 메시지 객체입니다.

데이터형이 object 인 이유는 받는 메시지가 JSON 일 수도 있고 Protobuf 메시지일 수도 있기 때문입니다. 등록한 핸들러에서 아래와 같이 적절한 데이터형으로 변환해서 사용해야 합니다.

// JSON
Dictionary<string, object> message = body as Dictionary<string, object>;

// Protobuf
FunMessage message = body as FunMessage;

메시지 전송¶

이제 메시지를 보낼 수 있는 기본적이 준비가 완료되었습니다. 아래 코드는 플러그인 샘플에서 echo 메시지를 보내는 예제입니다. 기본 프로토콜의 인코딩 타입을 구해서 해당 인코딩 타입의 메시지를 전송합니다. 예제에서는 기본 프로토콜이 변경될 수 있어 인코딩 타입을 매번 구하고 있지만 실제로 사용할 때는 어떤 메시지가 어느 프로토콜을 통해서 주고 받게 될지 이미 알고 있기 때문에 아래와 같이 구현할 필요는 없습니다.

// 기본 프로토콜 인코딩 타입을 구합니다.
FunEncoding encoding = network.GetEncoding(network.GetDefaultProtocol());
if (encoding == FunEncoding.kNone)
{
    // 앗, 등록된 Transport가 없습니다.
    DebugUtils.Log("You should attach the transport first.");
    return;
}

if (encoding == FunEncoding.kJson)
{
    // 기본적으로 Json은 MiniJSON을 사용합니다.
    // 다른 종류의 Json 라이브러리를 사용하고 싶다면 원하는 Json 라이브러리를 사용하는
    // JsonAccessor를 만들어 Transport의 JsonHelper를 변경하면 됩니다.
    Dictionary<string, object> message = new Dictionary<string, object>();
    message["message"] = "hello world";

    // SendMessage에 메시지 타입 이름과 메시지 객체를 전달합니다.
    network.SendMessage("echo", message);
}
else if (encoding == FunEncoding.kProtobuf)
{
    // echo 메시지를 생성합니다.
    PbufEchoMessage echo = new PbufEchoMessage();
    echo.msg = "hello proto";

    // echo 메시지를 포함하는 FunMessage 객체를 만듭니다.
    // 메시지는 항상 FunMessage의 extend 형태로 만들어야 합니다.
    FunMessage message = FunapiMessage.CreateFunMessage(echo, MessageType.pbuf_echo);

    // SendMessage에 메시지 타입과 메시지 객체를 전달합니다.
    network.SendMessage(MessageType.pbuf_echo, message);
}

Protobuf 메시지의 기본형은 FunMessage 입니다. 추가 메시지는 extend 형태로 되어있습니다. extend 메시지 중 0 ~ 15번까지는 예약된 메시지입니다. 사용자 메시지는 16번 필드부터 사용이 가능합니다.

MessageType 은 서버에서 .proto 파일들을 빌드해서 메시지 DLL을 만들 때 함께 생성되는 enum 리스트입니다. extend 된 메시지들의 숫자 대신 메시지 이름으로 사용할 수 있도록 도와주는 객체입니다.

Important

Unity에서 Protobuf-net 기반의 메시지를 보내려면 추가적인 빌드 과정을 따라야 합니다. Unity with protobuf-net 설명을 참고해주세요.

메시지 수신¶

서버로부터 메시지를 받으면 RegisterHandler 함수로 등록한 메시지 핸들러 함수가 호출됩니다. 모든 메시지마다 각각의 메시지 핸들러가 필요합니다. 메시지 핸들러 함수가 하나라고 해도 핸들러 등록은 메시지마다 각각 등록하셔야 합니다.

등록된 핸들러 함수에서 아래와 같이 메시지를 파싱해서 사용하면 됩니다.

[Json Message]

// 메시지 핸들러로 전달되는 메시지는 이미 Deserialize가 된 상태의 Json 객체가 넘어옵니다.
// 여기서는 Json 객체를 다시 string으로 Serialize 해서 Json 메시지 전체를 로그로 출력합니다.
string strJson = Json.Serialize(body as Dictionary<string, object>);
DebugUtils.Log("Received an echo message: {0}", strJson);

[Protobuf Message]

// 메시지 핸들러로 전달되는 body는 FunMessage 객체입니다.
FunMessage msg = body as FunMessage;

// Extend 된 메시지 타입을 GetMessage를 통해 얻어옵니다.
object obj = FunapiMessage.GetMessage(msg, MessageType.pbuf_echo);

// PbufEchoMessage 메시지의 msg 값을 로그로 출력합니다.
PbufEchoMessage echo = obj as PbufEchoMessage;
DebugUtils.Log("Received an echo message: {0}", echo.msg);

암호화된 메시지¶

서버와 메시지를 주고 받을 때 메시지 전체를 암호화할 수 있습니다.

암호화 타입¶

암호화 타입은 두 가지 종류가 있습니다.

public enum EncryptionType
{
    kIFunEngine1Encryption,
    kIFunEngine2Encryption
}

IFunEngine1Encryption 은 메시지를 주고 받을 때마다 암호화 키가 변경됩니다. 동일한 메시지를 보내도 암호화 키 값이 달라지게 됩니다. 이 암호화 방식은 TCP 프로토콜에서만 사용이 가능합니다. 추후 HTTP 프로토콜에도 추가 될 예정입니다.

IFunEngine2Encryption 은 고정된 암호화 키를 사용합니다. 따라서 ife1 방식이 더 안전하다고 할 수 있습니다. 이 방식은 모든 프로토콜에서 사용 가능합니다.

암호화 사용¶

암호화 기능을 사용하기 위해서 해야 할 작업은 간단합니다. FunapiTransport 생성 후 SetEncryption 함수를 호출해서 사용할 EncryptionType 을 정해주면 됩니다.

transport.SetEncryption(EncryptionType.kIFunEngine1Encryption);

EncryptionType 타입은 서버와 동일한 값을 사용해야 합니다.

TCP 의 경우 서버에서 두 종류를 모두 지원할 수도 있는데 이 때는 클라이언트에서 선택해서 사용할 수 있습니다. 메시지를 보낼 때마다 암호화 타입을 지정할 수도 있는데 SendMessage 함수를 호출할 때 인자로 EncryptionType 값을 정해주면 됩니다. SendMessage에서 EncryptionType 값을 지정하지 않으면 SetEncryption 함수를 통해 지정한 값(기본 값)으로 암호화하게 됩니다.

network.SendMessage("echo", message, EncryptionType.kIFunEngine2Encryption);

Tip

GitHub 에 배포된 클라이언트 플러그인은 암호화 기능이 포함되지 않은 무료 버전입니다. 유료 고객의 경우 iFun Engine support 로 요청 메일을 보내주시면 암호화 기능이 포함된 버전의 플러그인 소스를 보내드립니다.

Ping 사용 방법¶

네트워크의 연결 상태를 확인하기 위해 터미널에서 사용하는 ping 이라는 명령어가 있습니다. 플러그인에도 이와 비슷한 기능이 있는데 서버와의 연결이 유지되고 있는지 확인하는 용도로 사용할 수 있습니다. 모바일 환경에서는 연결을 유지하는데 있어서 많은 변수가 존재하는데 이로 인해 잦은 연결의 끊김이 발생할 수도 있습니다. 디바이스에 따라 네트워크 연결이 바뀌는 것을 빠르게 감지하지 못하는 경우도 있는데 플러그인의 Ping 기능을 사용해서 연결이 끊겼다고 판단될 때 좀 더 빠른 대응을 할 수 있습니다.

이 기능은 TCP 프로토콜에서만 사용 가능합니다.

Ping 설정¶

Ping 기능을 사용하려면 아래와 같이 EnablePing 값을 true 로 주면 됩니다.

FunapiTcpTransport transport = new FunapiTcpTransport(...);
...
// 이 값을 true로 주면 Ping 기능을 사용할 수 있습니다.
// EnablePing 의 기본 값은 false 입니다.
transport.EnablePing = true;

FunapiTcpTransport.EnablePing 에 입력하는 값은 Transport 가 시작하기 전에 입력한 값만 적용됩니다. Transport 가 시작된 이후에 이 값을 변경하면 연결이 끊긴 후 다시 시작할 때까지 반영이 되지 않습니다.

Ping 시간 설정¶

Ping 을 보내는 간격이나 응답을 기다리는 시간을 정할 수 있습니다. 기본 값은 3초 간격으로 Ping 을 보내고 최대 20초까지 응답을 기다립니다. 아래와 같은 방법으로 시간 값을 변경할 수 있습니다.

// Ping을 보내는 간격 값입니다.
transport.PingIntervalSeconds = 5;

// Ping 에 대한 서버의 응답을 기다리는 timeout 시간 값입니다.
transport.PingTimeoutSeconds = 22;

만약 PingTimeoutSeconds 에 지정된 시간 내에 서버에서 응답을 한 번도 못 받으면 Transport 의 연결이 종료되고 TransportDisconnectedCallback 함수가 호출됩니다.

Ping 값 확인¶

Ping 을 보낸 시점으로부터 서버에서 응답을 받은 시점까지의 시간 간격을 FunapiTransport 의 PingTime 값을 통해 확인할 수 있습니다.

디버그 로그(ENABLE_DEBUG)를 활성화하면 핑 값을 로그로 확인할 수도 있습니다.

서버 Ping¶

Ping 에는 클라이언트용 Ping 과 서버용 Ping 이 나뉘어져 있습니다. 서버든 클라이언트든 Ping 이 필요한 쪽만 활성화해서 사용할 수 있습니다. 서버는 MANIFEST 파일에서 값을 수정하면 됩니다.

아래는 서버의 MANIFEST 파일의 Ping 설정 값에 대한 예제입니다.

"SessionService": {
  ...
  "ping_sampling_interval_in_second": 30,
  "ping_message_size_in_byte": 0
},

ping_sampling_interval_in_second 값을 30으로 주면 30초에 도달할 때까지 2의 배수로 시간이 증가 (1, 2, 4, 8, 16, 30, 30, 30…) 하며 ping time을 측정합니다.