# Amazon GameLift Servers Realtime client API (C\$1) reference
<a name="realtime-sdk-csharp-ref"></a>

Use this reference guide to understand how to implement Realtime client API functionality into your multiplayer game clients. For guidance on how to integrate this API into your game clients, see [Integrate a game client for Amazon GameLift Servers Realtime](realtime-client.md).

The Realtime client API includes a set of synchronous API calls and asynchronous callbacks that enable a game client to connect to a Realtime server and exchange messages and data with other game clients via the server. 

This API is defined in the following libraries: 

Client.cs 
+ [Synchronous actions](realtime-sdk-csharp-ref-actions.md)
+ [Asynchronous callbacks](realtime-sdk-csharp-ref-callbacks.md)
+ [Data types](realtime-sdk-csharp-ref-datatypes.md)

**To set up the Realtime client API**

1. **Download the [Amazon GameLift ServersRealtime client SDK](https://aws.amazon.com/gamelift/getting-started).** 

1. **Build the C\$1 SDK libraries.** Locate the solution file `GameLiftRealtimeClientSdkNet45.sln`. See the `README.md` file for the C\$1 Server SDK for minimum requirements and additional build options. In an IDE, load the solution file. To generate the SDK libraries, restore the NuGet packages and build the solution.

1. **Add the Realtime Client libraries to your game client project.** 



# Amazon GameLift Servers Realtime client API (C\$1) reference: Actions
<a name="realtime-sdk-csharp-ref-actions"></a>

This C\$1 Realtime Client API reference can help you prepare your multiplayer game for use with Amazon GameLift Servers Realtime deployed on Amazon GameLift Servers fleets. 
+ Synchronous Actions
+ [Asynchronous Callbacks](realtime-sdk-csharp-ref-callbacks.md)
+ [Data Types](realtime-sdk-csharp-ref-datatypes.md)

## Client()
<a name="realtime-sdk-csharp-ref-actions-client"></a>

Initializes a new client to communicate with the Realtime server and identifies the type of connection to use. 

### Syntax
<a name="integration-server-sdk-csharp-ref-actions-client-syntax"></a>

```
public Client(ClientConfiguration configuration)
```

### Parameters
<a name="realtime-sdk-csharp-ref-actions-client-parameter"></a>

**clientConfiguration**  
Configuration details specifying the client/server connection type. You can opt to call Client() without this parameter; however, this approach results in an unsecured connection by default.  
Type: [ClientConfiguration](realtime-sdk-csharp-ref-datatypes.md#realtime-sdk-csharp-ref-datatypes-clientconfiguration)  
Required: No

### Return value
<a name="realtime-sdk-csharp-ref-actions-client-return"></a>

Returns an instance of the Realtime client for use with communicating with the Realtime server. 

## Connect()
<a name="realtime-sdk-csharp-ref-actions-connect"></a>

Requests a connection to a server process that is hosting a game session. 

### Syntax
<a name="integration-server-sdk-csharp-ref-actions-connect-syntax"></a>

```
public ConnectionStatus Connect(string endpoint, int remoteTcpPort, int listenPort, ConnectionToken token)
```

### Parameters
<a name="realtime-sdk-csharp-ref-actions-connect-parameter"></a>

**endpoint**  
DNS name or IP address of the game session to connect to. The endpoint is specified in a `GameSession` object, which is returned in response to a client call to the *AWS SDK Amazon GameLift Servers API* actions [StartGameSessionPlacement](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StartGameSessionPlacement.html), [CreateGameSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreateGameSession.html), or [DescribeGameSessions](https://docs.aws.amazon.com/gamelift/latest/apireference/API_SearchGameSessions.html).   
If the Realtime server is running on a fleet with a TLS certificate, you must use the DNS name. 
Type: String  
Required: Yes

**remoteTcpPort**  
Port number for the TCP connection assigned to the game session. This information is specified in a `GameSession` object, which is returned in response to a [StartGameSessionPlacement](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StartGameSessionPlacement.html) [CreateGameSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreateGameSession.html), or [DescribeGameSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribeGameSession.html) request.  
Type: Integer  
Valid Values: 1900 to 2000.  
Required: Yes

**listenPort**  
Port number that the game client is listening on for messages sent using the UDP channel.   
Type: Integer  
Valid Values: 33400 to 33500.  
Required: Yes

**token**  
Optional information that identifies the requesting game client to the server process.   
Type: [ConnectionToken](realtime-sdk-csharp-ref-datatypes.md#realtime-sdk-csharp-ref-datatypes-connectiontoken)  
Required: Yes

### Return value
<a name="realtime-sdk-csharp-ref-actions-connect-return"></a>

Returns a [ConnectionStatus](realtime-sdk-csharp-ref-datatypes.md#realtime-sdk-csharp-ref-datatypes-enums) enum value indicating the client's connection status. 

## Disconnect()
<a name="realtime-sdk-csharp-ref-actions-disconnect"></a>

When connected to a game session, disconnects the game client from the game session. 

### Syntax
<a name="realtime-sdk-csharp-ref-actions-disconnect-syntax"></a>

```
public void Disconnect()
```

### Parameters
<a name="realtime-sdk-csharp-ref-actions-disconnect-parameter"></a>

This action has no parameters.

### Return value
<a name="realtime-sdk-csharp-ref-actions-disconnect-return"></a>

This method does not return anything.

## NewMessage()
<a name="realtime-sdk-csharp-ref-actions-newmessage"></a>

Creates a new message object with a specified operation code. Once a message object is returned, complete the message content by specifying a target, updating the delivery method, and adding a data payload as needed. Once completed, send the message using `SendMessage()`.

### Syntax
<a name="realtime-sdk-csharp-ref-actions-newmessage-syntax"></a>

```
public RTMessage NewMessage(int opCode)
```

### Parameters
<a name="realtime-sdk-csharp-ref-actions-newmessage-parameter"></a>

**opCode**  
Developer-defined operation code that identifies a game event or action, such as a player move or a server notification.   
Type: Integer  
Required: Yes

### Return value
<a name="realtime-sdk-csharp-ref-actions-newmessage-return"></a>

Returns an [RTMessage](realtime-sdk-csharp-ref-datatypes.md#realtime-sdk-csharp-ref-datatypes-rtmessage) object containing the specified operation code and default delivery method. The delivery intent parameter is set to `FAST` by default. 

## SendMessage()
<a name="realtime-sdk-csharp-ref-actions-sendmessage"></a>

 Sends a message to a player or group using the delivery method specified.

### Syntax
<a name="realtime-sdk-csharp-ref-actions-sendmessage-syntax"></a>

```
public void SendMessage(RTMessage message)
```

### Parameters
<a name="realtime-sdk-csharp-ref-actions-sendmessage-parameter"></a>

**message**  
Message object that specifies the target recipient, delivery method, and message content.   
Type: [RTMessage](realtime-sdk-csharp-ref-datatypes.md#realtime-sdk-csharp-ref-datatypes-rtmessage)  
Required: Yes

### Return value
<a name="realtime-sdk-csharp-ref-actions-sendmessage-return"></a>

This method does not return anything. 

## JoinGroup()
<a name="realtime-sdk-csharp-ref-actions-joingroup"></a>

Adds the player to the membership of a specified group. Groups can contain any of the players that are connected to the game. Once joined, the player receives all future messages sent to the group and can send messages to the entire group.

### Syntax
<a name="realtime-sdk-csharp-ref-actions-joingroup-syntax"></a>

```
public void JoinGroup(int targetGroup)
```

### Parameters
<a name="realtime-sdk-csharp-ref-actions-joingroup-parameter"></a>

**targetGroup**  
Unique ID that identifies the group to add the player to. Group IDs are developer-defined.  
Type: Integer  
Required: Yes

### Return value
<a name="realtime-sdk-csharp-ref-actions-joingroup-return"></a>

This method does not return anything. Because this request is sent using the reliable (TCP) delivery method, a failed request triggers the callback [OnError()](realtime-sdk-csharp-ref-callbacks.md#realtime-sdk-csharp-ref-callbacks-onerror). 

## LeaveGroup()
<a name="realtime-sdk-csharp-ref-actions-leavegroup"></a>

Removes the player from the membership of a specified group. Once no longer in the group, the player does not receive messages sent to the group and cannot send messages to the entire group.

### Syntax
<a name="integration-server-sdk-csharp-ref-actions-leavegroup-syntax"></a>

```
public void LeaveGroup(int targetGroup)
```

### Parameters
<a name="realtime-sdk-csharp-ref-actions-leavegroup-parameter"></a>

**targetGroup**  
Unique ID identifying the group to remove the player from. Group IDs are developer-defined.  
Type: Integer  
Required: Yes

### Return value
<a name="realtime-sdk-csharp-ref-actions-leavegroup-return"></a>

This method does not return anything. Because this request is sent using the reliable (TCP) delivery method, a failed request triggers the callback [OnError()](realtime-sdk-csharp-ref-callbacks.md#realtime-sdk-csharp-ref-callbacks-onerror).

## RequestGroupMembership()
<a name="realtime-sdk-csharp-ref-actions-requestgroupmembership"></a>

Requests that a list of players in the specified group be sent to the game client. Any player can request this information, regardless of whether they are a member of the group or not. In response to this request, the membership list is sent to the client via an [OnGroupMembershipUpdated()](realtime-sdk-csharp-ref-callbacks.md#realtime-sdk-csharp-ref-callbacks-ongroupupdate) callback.

### Syntax
<a name="realtime-sdk-csharp-ref-actions-requestgroupmembership-syntax"></a>

```
public void RequestGroupMembership(int targetGroup)
```

### Parameters
<a name="realtime-sdk-csharp-ref-actions-requestgroupmembership-parameter"></a>

**targetGroup**  
Unique ID identifying the group to get membership information for. Group IDs are developer-defined.  
Type: Integer  
Required: Yes

### Return value
<a name="realtime-sdk-csharp-ref-actions-requestgroupmembership-return"></a>

This method does not return anything. 

# Amazon GameLift Servers Realtime client API (C\$1) reference: Asynchronous callbacks
<a name="realtime-sdk-csharp-ref-callbacks"></a>

Use this C\$1 Realtime Client API reference to help you prepare your multiplayer game for use with Amazon GameLift Servers Realtime deployed on Amazon GameLift Servers fleets. 
+ [Synchronous Actions](realtime-sdk-csharp-ref-actions.md)
+ Asynchronous Callbacks
+ [Data Types](realtime-sdk-csharp-ref-datatypes.md)

A game client needs to implement these callback methods to respond to events. The Realtime server invokes these callbacks to send game-related information to the game client. Callbacks for the same events can also be implemented with custom game logic in the Realtime server script. See [Script callbacks for Amazon GameLift Servers Realtime](realtime-script-callbacks.md).

Callback methods are defined in `ClientEvents.cs`.

## OnOpen()
<a name="realtime-sdk-csharp-ref-callbacks-onopen"></a>

Invoked when the server process accepts the game client's connection request and opens a connection.

### Syntax
<a name="realtime-sdk-csharp-ref-callbacks-onopen-syntax"></a>

```
public void OnOpen()
```

### Parameters
<a name="realtime-sdk-csharp-ref-callbacks-onopen-parameter"></a>

This method takes no parameters.

### Return value
<a name="realtime-sdk-csharp-ref-callbacks-onopen-return"></a>

This method does not return anything. 

## OnClose()
<a name="realtime-sdk-csharp-ref-callbacks-onclose"></a>

Invoked when the server process terminates the connection with the game client, such as after a game session ends.

### Syntax
<a name="realtime-sdk-csharp-ref-callbacks-onclose-syntax"></a>

```
public void OnClose()
```

### Parameters
<a name="realtime-sdk-csharp-ref-callbacks-onclose-parameter"></a>

This method takes no parameters.

### Return value
<a name="realtime-sdk-csharp-ref-callbacks-onclose-return"></a>

This method does not return anything. 

## OnError()
<a name="realtime-sdk-csharp-ref-callbacks-onerror"></a>

Invoked when a failure occurs for a Realtime Client API request. This callback can be customized to handle a variety of connection errors.

### Syntax
<a name="realtime-sdk-csharp-ref-callbacks-onerror-syntax"></a>

```
private void OnError(byte[] args)
```

### Parameters
<a name="realtime-sdk-csharp-ref-callbacks-onerror-parameter"></a>

This method takes no parameters.

### Return value
<a name="realtime-sdk-csharp-ref-callbacks-onerror-return"></a>

This method does not return anything. 

## OnDataReceived()
<a name="realtime-sdk-csharp-ref-callbacks-ondata"></a>

Invoked when the game client receives a message from the Realtime server. This is the primary method by which messages and notifications are received by a game client.

### Syntax
<a name="realtime-sdk-csharp-ref-callbacks-ondata-syntax"></a>

```
public void OnDataReceived(DataReceivedEventArgs dataReceivedEventArgs)
```

### Parameters
<a name="realtime-sdk-csharp-ref-callbacks-ondata-parameter"></a>

**dataReceivedEventArgs**  
Information related to message activity.  
Type: [DataReceivedEventArgs](realtime-sdk-csharp-ref-datatypes.md#realtime-sdk-csharp-ref-datatypes-dataeventargs)  
Required: Yes

### Return value
<a name="realtime-sdk-csharp-ref-callbacks-ondata-return"></a>

This method does not return anything. 

## OnGroupMembershipUpdated()
<a name="realtime-sdk-csharp-ref-callbacks-ongroupupdate"></a>

Invoked when the membership for a group that the player belongs to has been updated. This callback is also invoked when a client calls `RequestGroupMembership`.

### Syntax
<a name="realtime-sdk-csharp-ref-callbacks-ongroupupdate-syntax"></a>

```
public void OnGroupMembershipUpdated(GroupMembershipEventArgs groupMembershipEventArgs)
```

### Parameters
<a name="realtime-sdk-csharp-ref-callbacks-ongroupupdate-parameter"></a>

**groupMembershipEventArgs**  
Information related to group membership activity.   
Type: [GroupMembershipEventArgs](realtime-sdk-csharp-ref-datatypes.md#realtime-sdk-csharp-ref-datatypes-groupeventargs)  
Required: Yes

### Return value
<a name="realtime-sdk-csharp-ref-callbacks-ongroupupdate-return"></a>

This method does not return anything. 

# Amazon GameLift Servers Realtime client API (C\$1) reference: Data types
<a name="realtime-sdk-csharp-ref-datatypes"></a>

This C\$1 Realtime Client API reference can help you prepare your multiplayer game for use with Amazon GameLift Servers Realtime deployed on Amazon GameLift Servers fleets. 
+ [Synchronous Actions](realtime-sdk-csharp-ref-actions.md)
+ [Asynchronous Callbacks](realtime-sdk-csharp-ref-callbacks.md)
+ Data Types

## ClientConfiguration
<a name="realtime-sdk-csharp-ref-datatypes-clientconfiguration"></a>

Information about how the game client connects to a Realtime server. 

### Contents
<a name="realtime-sdk-csharp-ref-datatypes-clientconfiguration-contents"></a>

**ConnectionType**  
Type of client/server connection to use, either secured or unsecured. If you don't specify a connection type, the default is unsecured.   
When connecting to a Realtime server on a secured fleet with a TLS certificate, you must use the value RT\$1OVER\$1WSS\$1DTLS\$1TLS12. 
Type: A `ConnectionType` [enum](#realtime-sdk-csharp-ref-datatypes-enums) value.  
Required: No

## ConnectionToken
<a name="realtime-sdk-csharp-ref-datatypes-connectiontoken"></a>

Information about the game client and/or player that is requesting a connection with a Realtime server.

### Contents
<a name="realtime-sdk-csharp-ref-datatypes-connectiontoken-contents"></a>

**playerSessionId**  
Unique ID issued by Amazon GameLift Servers when a new player session is created. A player session ID is specified in a `PlayerSession` object, which is returned in response to a client call to the *GameLift API* actions [ StartGameSessionPlacement](https://docs.aws.amazon.com/gamelift/latest/apireference/API_StartGameSessionPlacement.html), [ CreateGameSession](https://docs.aws.amazon.com/gamelift/latest/apireference/API_CreateGameSession.html), [ DescribeGameSessionPlacement](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribeGameSessionPlacement.html), or [ DescribePlayerSessions](https://docs.aws.amazon.com/gamelift/latest/apireference/API_DescribePlayerSessions.html).  
Type: String  
Required: Yes

**payload**  
Developer-defined information to be communicated to the Realtime server on connection. This includes any arbitrary data that might be used for a custom sign-in mechanism. For examples, a payload may provide authentication information to be processed by the Realtime server script before allowing a client to connect.  
Type: byte array   
Required: No

## RTMessage
<a name="realtime-sdk-csharp-ref-datatypes-rtmessage"></a>

Content and delivery information for a message. A message must specify either a target player or a target group. 

### Contents
<a name="realtime-sdk-csharp-ref-datatypes-rtmessage-contents"></a>

**opCode**  
Developer-defined operation code that identifies a game event or action, such as a player move or a server notification. A message's Op code provides context for the data payload that is being provided. Messages that are created using NewMessage() already have the operation code set, but it can be changed at any time.   
Type: Integer  
Required: Yes

**targetPlayer**  
Unique ID identifying the player who is the intended recipient of the message being sent. The target may be the server itself (using the server ID) or another player (using a player ID).   
Type: Integer   
Required: No

**targetGroup**  
Unique ID identifying the group that is the intended recipient of the message being sent. Group IDs are developer defined.   
Type: Integer   
Required: No

**deliveryIntent**  
Indicates whether to send the message using the reliable TCP connection or using the fast UDP channel. Messages created using [NewMessage()](realtime-sdk-csharp-ref-actions.md#realtime-sdk-csharp-ref-actions-newmessage).  
Type: DeliveryIntent enum  
Valid values: FAST \$1 RELIABLE  
Required: Yes

**payload**  
Message content. This information is structured as needed to be processed by the game client based on the accompanying operation code. It may contain game state data or other information that needs to be communicated between game clients or between a game client and the Realtime server.  
Type: Byte array   
Required: No

## DataReceivedEventArgs
<a name="realtime-sdk-csharp-ref-datatypes-dataeventargs"></a>

Data provided with an [OnDataReceived()](realtime-sdk-csharp-ref-callbacks.md#realtime-sdk-csharp-ref-callbacks-ondata) callback. 

### Contents
<a name="realtime-sdk-csharp-ref-datatypes-dataeventargs-contents"></a>

**sender**  
Unique ID identifying the entity (player ID or server ID) who originated the message.  
Type: Integer   
Required: Yes

**opCode**  
Developer-defined operation code that identifies a game event or action, such as a player move or a server notification. A message's Op code provides context for the data payload that is being provided.   
Type: Integer   
Required: Yes

**data**  
Message content. This information is structured as needed to be processed by the game client based on the accompanying operation code. It may contain game state data or other information that needs to be communicated between game clients or between a game client and the Realtime server.  
Type: Byte array   
Required: No

## GroupMembershipEventArgs
<a name="realtime-sdk-csharp-ref-datatypes-groupeventargs"></a>

Data provided with an [OnGroupMembershipUpdated()](realtime-sdk-csharp-ref-callbacks.md#realtime-sdk-csharp-ref-callbacks-ongroupupdate) callback. 

### Contents
<a name="realtime-sdk-csharp-ref-datatypes-groupeventargs-contents"></a>

**sender**  
Unique ID identifying the player who requested a group membership update.  
Type: Integer   
Required: Yes

**opCode**  
Developer-defined operation code that identifies a game event or action.   
Type: Integer   
Required: Yes

**groupId**  
Unique ID identifying the group that is the intended recipient of the message being sent. Group IDs are developer defined.  
Type: Integer   
Required: Yes

**playerId**  
List of player IDs who are current members of the specified group.   
Type: Integer array   
Required: Yes

## Enums
<a name="realtime-sdk-csharp-ref-datatypes-enums"></a>

Enums defined for the client SDK for Amazon GameLift Servers Realtime are defined as follows: 

**ConnectionStatus**  
+ CONNECTED – Game client is connected to the Realtime server with a TCP connection only. All messages regardless of delivery intent are sent via TCP.
+ CONNECTED\$1SEND\$1FAST – Game client is connected to the Realtime server with a TCP and a UDP connection. However, the ability to receive messages via UDP is not yet verified; as a result, all messages sent to the game client use TCP. 
+ CONNECTED\$1SEND\$1AND\$1RECEIVE\$1FAST – Game client is connected to the Realtime server with a TCP and a UDP connection. The game client can send and receive messages using either TCP or UDP. 
+ CONNECTING Game client has sent a connection request and the Realtime server is processing it.
+ DISCONNECTED\$1CLIENT\$1CALL – Game client was disconnected from the Realtime server in response to a [Disconnect()](realtime-sdk-csharp-ref-actions.md#realtime-sdk-csharp-ref-actions-disconnect)request from the game client.
+ DISCONNECTED – Game client was disconnected from the Realtime server for a reason other than a client disconnect call.

**ConnectionType**  
+ RT\$1OVER\$1WSS\$1DTLS\$1TLS12 – Secure connection type. 

  For use with Realtime servers that are running on an Amazon GameLift Servers fleet with a TLS certificate generated. When using a secure connection, TCP traffic is encrypted using TLS 1.2, and UDP traffic is encrypted using DTLS 1.2.
+ RT\$1OVER\$1WS\$1UDP\$1UNSECURED – Non-secure connection type.
+ RT\$1OVER\$1WEBSOCKET – Non-secure connection type. This value is no longer preferred.

**DeliveryIntent**  
+ FAST – Delivered using a UDP channel. 
+ RELIABLE – Delivered using a TCP connection.