/// <summary>
/// Retrieves connection information for Discord's Gateway API.
/// </summary>
/// <param name="token">CancellationToken used to handle cancellation of the connection</param>
/// <returns>a <see cref="GetGatewayResponseObject"/> containing information to connect to the Gateway</returns>
public virtual async Task <GetGatewayResponseObject> AuthenticateAsync(CancellationToken token)
{
token.ThrowIfCancellationRequested();
GetGatewayResponseObject response = Credentials.IsBearerToken
? await GatewayRoutes.GetGatewayAsync(Gateway.Rest, token)
: await GatewayRoutes.GetBotGatewayAsync(Gateway.Rest, token);
return(response);
}
/// <summary>
/// Connects to the Gateway API using the provided <see cref="GetGatewayResponseObject"/>
/// Disconnect with <see cref="DisconnectAsync"/> or by cancelling the provided <see cref="CancellationToken"/>.
/// Returns a <see cref="Task"/> which may be awaited to block the calling thread
/// </summary>
/// <param name="externalToken">CancellationToken used for managing cancellation of the connection</param>
/// <returns>a <see cref="Task"/> which may be awaited to block the calling thread</returns>
public virtual async Task <Task> ConnectAsync(CancellationToken externalToken, GetGatewayResponseObject connectionInfo)
{
if (externalToken == null)
{
throw new ArgumentNullException("externalToken");
}
_externalToken = externalToken;
linkedTokenSource = CancellationTokenSource.CreateLinkedTokenSource(externalToken, Gateway.GatewayTokenSource.Token);
_connectionInfo = connectionInfo;
return(await InternalConnectAsync());
}
/// <summary>
/// Tests authentication then connects to the Gateway API.
/// Disconnect with <see cref="DisconnectAsync"/> or by cancelling the provided <see cref="CancellationToken"/>.
/// Returns a <see cref="Task"/> which may be awaited to block the calling thread
/// </summary>
/// <param name="externalToken">CancellationToken used for managing cancellation of the connection</param>
/// <returns>a <see cref="Task"/> which may be awaited to block the calling thread</returns>
public virtual async Task <Task> ConnectAsync(CancellationToken externalToken)
{
if (externalToken == null)
{
throw new ArgumentNullException("externalToken");
}
_externalToken = externalToken;
//Create a TokenSource from the provided client CancellationToken and our own internal token source's token
//If the client ever cancels their token then this TokenSource will propagate cancellation
//Likewise, if we ever cancel our token then this TokenSource will propagate cancellation
linkedTokenSource = CancellationTokenSource.CreateLinkedTokenSource(externalToken, Gateway.GatewayTokenSource.Token);
//Retrieve information required to connect to the Gateway.
//This will throw an exception if it fails.
_connectionInfo = await AuthenticateAsync(linkedTokenSource.Token);
return(await InternalConnectAsync());
}