/// <summary>
/// Create a Threat List Update Query.
/// </summary>
/// <param name="threatListDescriptor">
/// A <see cref="Browsing.ThreatListDescriptor" /> identifying the <see cref="ThreatList" /> to retrieve.
/// </param>
/// <param name="threatListState">
/// The state, formatted as a hexadecimal encoded string, of the <see cref="ThreatList" /> identified by
/// <paramref name="threatListDescriptor" />. This should be the value returned by the Google Safe Browsing
/// API when the threat list was most recently retrieved. An invalid state will be ignored by the Google
/// Safe Browsing API and will force the threat list to be retrieved as a
/// <see cref="ThreatListUpdateType.Full" /> update. A null reference indicates the state of the threat
/// list is unknown and will force the threat list to be retrieved as a
/// <see cref="ThreatListUpdateType.Full" /> update.
/// </param>
/// <param name="updateConstraints">
/// The <see cref="ThreatListUpdateConstraints" /> to apply when the <see cref="ThreatList" /> identified
/// by <paramref name="threatListDescriptor" /> is retrieved. A null reference indicates no update
/// constraints should be applied.
/// </param>
/// <exception cref="System.ArgumentNullException">
/// Thrown if <paramref name="threatListDescriptor" /> is a null reference.
/// </exception>
/// <exception cref="System.FormatException">
/// Thrown if <paramref name="threatListState" /> is not a null reference and it is not hexadecimal
/// encoded.
/// </exception>
public ThreatListUpdateQuery(ThreatListDescriptor threatListDescriptor, string threatListState, ThreatListUpdateConstraints updateConstraints)
{
Guard.ThrowIf(nameof(threatListDescriptor), threatListDescriptor).Null();
this.ThreatListDescriptor = threatListDescriptor;
this.ThreatListState = CreateThreatListState(threatListState);
this.UpdateConstraints = updateConstraints;
// <summary>
// Create Threat List State.
// </summary>
string CreateThreatListState(string cThreatListState)
{
if (cThreatListState != null)
{
// ...
//
// Throws an exception if the operation fails.
var cIsThreatListStateHexadecimalEncoded = cThreatListState.IsHexadecimalEncoded();
if (!cIsThreatListStateHexadecimalEncoded)
{
var cDetailMessage = $"A threat list state ({cThreatListState}) is not hexadecimal encoded.";
throw new FormatException(cDetailMessage);
}
}
return(cThreatListState);
}
}
/// <summary>
/// Create a Threat List Update Query.
/// </summary>
/// <param name="builder">
/// A <see cref="ThreatListUpdateQueryBuilder" /> to initialize the threat list update query with.
/// </param>
/// <exception cref="System.ArgumentNullException">
/// Thrown if <paramref name="builder" /> is a null reference.
/// </exception>
internal ThreatListUpdateQuery(ThreatListUpdateQueryBuilder builder)
{
Guard.ThrowIf(nameof(builder), builder).Null();
Guard.ThrowIf(nameof(builder), builder.ThreatListDescriptor).Null();
this.ThreatListDescriptor = builder.ThreatListDescriptor;
this.ThreatListState = builder.ThreatListState;
this.UpdateConstraints = builder.UpdateConstraints;
}
/// <summary>
/// Set Update Constraints.
/// </summary>
/// <param name="valueAction">
/// An action to create the <see cref="ThreatListUpdateConstraints" /> to apply when the
/// <see cref="ThreatList" /> is retrieved.
/// </param>
/// <returns>
/// This threat list update query builder.
/// </returns>
/// <exception cref="System.ArgumentNullException">
/// Thrown if <paramref name="valueAction" /> is a null reference.
/// </exception>
public ThreatListUpdateQueryBuilder SetUpdateConstraints(Func <ThreatListUpdateConstraintsBuilder, ThreatListUpdateConstraints> valueAction)
{
Guard.ThrowIf(nameof(valueAction), valueAction).Null();
// ...
//
// Throws an exception if the operation fails.
var threatListUpdateConstraintsBuilder = ThreatListUpdateConstraints.Build();
var threatListUpdateConstraints = valueAction(threatListUpdateConstraintsBuilder);
this.SetUpdateConstraints(threatListUpdateConstraints);
return(this);
}
/// <summary>
/// Build a Threat List Update Constraints.
/// </summary>
/// <returns>
/// A <see cref="ThreatListUpdateConstraints" />.
/// </returns>
public ThreatListUpdateConstraints Build()
{
var threatListUpdateConstraints = new ThreatListUpdateConstraints(this);
// ...
//
// Reinitialize the builder's state to prevent it from corrupting the immutable built object's state after
// its built. If the object holds a reference to the builder's state, any mutation to the builder's state
// will be reflected in the built object's state.
this.ClientLocation = null;
this.MaximumDatabaseEntries = default;
this.MaximumResponseEntries = default;
this.ThreatListLanguage = null;
this.ThreatListLocation = null;
return(threatListUpdateConstraints);
}
/// <summary>
/// Build a Threat List Update Query.
/// </summary>
/// <returns>
/// A <see cref="ThreatListUpdateQuery" />.
/// </returns>
public ThreatListUpdateQuery Build()
{
// ...
//
// Throws an exception if the operation fails.
var threatListUpdateQuery = new ThreatListUpdateQuery(this);
// ...
//
// Reinitialize the builder's state to prevent it from corrupting the immutable built object's state after
// its built. If the object holds a reference to the builder's state, any mutation to the builder's state
// will be reflected in the built object's state.
this.ThreatListDescriptor = null;
this.ThreatListState = null;
this.UpdateConstraints = null;
return(threatListUpdateQuery);
}
/// <summary>
/// Create a Threat List Update Constraints.
/// </summary>
static ThreatListUpdateConstraints()
{
ThreatListUpdateConstraints.Default = CreateDefault();
// <summary>
// Create Default Threat List Update Constraints.
// </summary>
ThreatListUpdateConstraints CreateDefault()
{
var cThreatListUpdateConstraints = ThreatListUpdateConstraints.Build()
.SetThreatListLocation(null)
.SetClientLocation(null)
.SetMaximumDatabaseEntries(0)
.SetMaximumResponseEntries(0)
.SetThreatListLanguage(null)
.Build();
return(cThreatListUpdateConstraints);
}
}
/// <summary>
/// Set Update Constraints.
/// </summary>
/// <param name="value">
/// The <see cref="ThreatListUpdateConstraints" /> to apply when the <see cref="ThreatList" /> is
/// retrieved. A null reference indicates no update constraints should be applied.
/// </param>
/// <returns>
/// This threat list update query builder.
/// </returns>
public ThreatListUpdateQueryBuilder SetUpdateConstraints(ThreatListUpdateConstraints value)
{
this.UpdateConstraints = value;
return(this);
}
/// <summary>
/// Get Threat List Updates Asynchronously.
/// </summary>
/// <param name="this">
/// A <see cref="IBrowsingClient" />.
/// </param>
/// <param name="threatList">
/// A <see cref="ThreatList" /> to retrieve.
/// </param>
/// <param name="updateConstraints">
/// The <see cref="ThreatListUpdateConstraints" /> to apply when <paramref name="threatList" /> is
/// retrieved. A null reference indicates no <see cref="ThreatListUpdateConstraints" /> should be applied.
/// </param>
/// <param name="cancellationToken">
/// A cancellation token to cancel the asynchronous operation with.
/// </param>
/// <returns>
/// A <see cref="ThreatListUpdateResponse" />.
/// </returns>
/// <exception cref="Gee.External.Browsing.Clients.BrowsingClientException">
/// Thrown if an error communicating with the Google Safe Browsing API occurs.
/// </exception>
/// <exception cref="System.ArgumentNullException">
/// Thrown if <paramref name="this" /> is a null reference, or if <paramref name="threatList" /> is a
/// null reference.
/// </exception>
/// <exception cref="System.ObjectDisposedException">
/// Thrown if the <paramref name="this" /> is disposed.
/// </exception>
/// <exception cref="System.OperationCanceledException">
/// Thrown if the asynchronous operation is cancelled.
/// </exception>
/// <exception cref="System.TimeoutException">
/// Thrown if communication with the Google Safe Browsing API times out.
/// </exception>
public static Task <ThreatListUpdateResponse> GetThreatListUpdatesAsync(this IBrowsingClient @this, ThreatList threatList, ThreatListUpdateConstraints updateConstraints, CancellationToken cancellationToken)
{
Guard.ThrowIf(nameof(@this), @this).Null();
Guard.ThrowIf(nameof(threatList), threatList).Null();
var threatListUpdateRequestBuilder = ThreatListUpdateRequest.Build();
threatListUpdateRequestBuilder.AddQuery(b => {
b.SetThreatListDescriptor(threatList.Descriptor);
b.SetThreatListState(threatList.State);
b.SetUpdateConstraints(updateConstraints);
return(b.Build());
});
// ...
//
// Throws an exception if the operation fails.
var threatListUpdateRequest = threatListUpdateRequestBuilder.Build();
var getThreatListUpdatesTask = @this.GetThreatListUpdatesAsync(threatListUpdateRequest, cancellationToken);
return(getThreatListUpdatesTask);
}
/// <summary> /// Get Threat List Updates Asynchronously. /// </summary> /// <param name="this"> /// A <see cref="IBrowsingClient" />. /// </param> /// <param name="threatList"> /// A <see cref="ThreatList" /> to retrieve. /// </param> /// <param name="updateConstraints"> /// The <see cref="ThreatListUpdateConstraints" /> to apply when <paramref name="threatList" /> is /// retrieved. A null reference indicates no <see cref="ThreatListUpdateConstraints" /> should be applied. /// </param> /// <returns> /// A <see cref="ThreatListUpdateResponse" />. /// </returns> /// <exception cref="Gee.External.Browsing.Clients.BrowsingClientException"> /// Thrown if an error communicating with the Google Safe Browsing API occurs. /// </exception> /// <exception cref="System.ArgumentNullException"> /// Thrown if <paramref name="this" /> is a null reference, or if <paramref name="threatList" /> is a /// null reference. /// </exception> /// <exception cref="System.ObjectDisposedException"> /// Thrown if the <paramref name="this" /> is disposed. /// </exception> /// <exception cref="System.TimeoutException"> /// Thrown if communication with the Google Safe Browsing API times out. /// </exception> public static Task <ThreatListUpdateResponse> GetThreatListUpdatesAsync(this IBrowsingClient @this, ThreatList threatList, ThreatListUpdateConstraints updateConstraints) => @this.GetThreatListUpdatesAsync(threatList, updateConstraints, CancellationToken.None);
