Class ResilientUnmanagedBrowsingDatabase

Resilient Unmanaged Database.

Inheritance
System.Object
BaseResilientBrowsingDatabase
ResilientUnmanagedBrowsingDatabase
Implements
System.IDisposable
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.ToString()
Namespace: Gee.External.Browsing.Databases
Assembly: Gee.External.Browsing.dll
Syntax
public sealed class ResilientUnmanagedBrowsingDatabase : BaseResilientBrowsingDatabase, IUnmanagedBrowsingDatabase, IDisposable
Remarks

Represents a resilient unmanaged database that automatically retries failed operations performed on an IUnmanagedBrowsingDatabase. The number of retry attempts is either caller or implementation specific if you do not specify a value. Between each retry attempt, the resilient unmanaged database will pause for an implementation specific interval. If all retry attempts are exhausted and the attempted operation never succeeds, the exception the failed operation threw will be propagated up to you.

If you specify a number of retry attempts when you create a resilient unmanaged database, be practical with the value you specify. The resilient unmanaged database will pause for an implementation specific interval between each retry attempt, which effectively means if an attempted operation always fails, the exception it threw will not be propagated up to you until all the retry attempts are exhausted. If you specify a very high number of retry attempts, this could have self inflicted performance implications.

When you create a resilient unmanaged database, you can specify whether or not it takes ownership of the unmanaged database you want to proxy to and dispose it when the resilient unmanaged database itself is disposed. The recommended behavior is that you allow the resilient unmanaged database to take ownership of the unmanaged database you want to proxy to but take note that if you reference or dispose the unmanaged database you want to proxy to after you create the resilient unmanaged database, the behavior of the resilient unmanaged database and unmanaged database you want to proxy to is undefined.

Since a resilient unmanaged database itself implements IUnmanagedBrowsingDatabase, it is technically possible to create a new resilient unmanaged database for an existing resilient unmanaged database, though the reasons for doing so, in most cases, are unjustified. To avoid doing do, consider creating a resilient unmanaged database using Create(IUnmanagedBrowsingDatabase), or one of its overloads, instead one of the constructor overloads. Create(IUnmanagedBrowsingDatabase) will conveniently create a resilient unmanaged database if, and only if, the unmanaged database you want to proxy to itself is not a resilient unmanaged database.

Constructors

ResilientUnmanagedBrowsingDatabase(IUnmanagedBrowsingDatabase)

Create a Resilient Unmanaged Database.

Declaration
public ResilientUnmanagedBrowsingDatabase(IUnmanagedBrowsingDatabase database)
Parameters
Type Name Description
IUnmanagedBrowsingDatabase database

An IUnmanagedBrowsingDatabase to proxy to. The resilient unmanaged database takes ownership of database and will dispose it when the resilient unmanaged database itself is disposed. If you reference or dispose database after you create the resilient unmanaged database, the behavior of the resilient unmanaged database and database is undefined.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if database is a null reference.

ResilientUnmanagedBrowsingDatabase(IUnmanagedBrowsingDatabase, Int32)

Create a Resilient Unmanaged Database.

Declaration
public ResilientUnmanagedBrowsingDatabase(IUnmanagedBrowsingDatabase database, int retryAttempts)
Parameters
Type Name Description
IUnmanagedBrowsingDatabase database

An IUnmanagedBrowsingDatabase to proxy to. The resilient unmanaged database takes ownership of database and will dispose it when the resilient unmanaged database itself is disposed. If you reference or dispose database after you create the resilient unmanaged database, the behavior of the resilient unmanaged database and database is undefined.
System.Int32 retryAttempts

The number of attempts a failed operation should be retried.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if database is a null reference.
System.ArgumentOutOfRangeException

Thrown if retryAttempts is less than or equal to 0.

ResilientUnmanagedBrowsingDatabase(IUnmanagedBrowsingDatabase, Int32, Boolean)

Create a Resilient Unmanaged Database.

Declaration
public ResilientUnmanagedBrowsingDatabase(IUnmanagedBrowsingDatabase database, int retryAttempts, bool ownDatabase)
Parameters
Type Name Description
IUnmanagedBrowsingDatabase database

An IUnmanagedBrowsingDatabase to proxy to.
System.Int32 retryAttempts

The number of attempts a failed operation should be retried.
System.Boolean ownDatabase

A boolean flag indicating whether or not the resilient unmanaged database takes ownership of database and disposes it when the resilient unmanaged database itself is disposed. If the resilient unmanaged database takes ownership of database and you reference or dispose database after you create the resilient unmanaged database, the behavior of the resilient unmanaged database and database is undefined.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if database is a null reference.
System.ArgumentOutOfRangeException

Thrown if retryAttempts is less than or equal to 0.

Methods

Create(IUnmanagedBrowsingDatabase)

Create a Resilient Unmanaged Database.

Declaration
public static ResilientUnmanagedBrowsingDatabase Create(IUnmanagedBrowsingDatabase database)
Parameters
Type Name Description
IUnmanagedBrowsingDatabase database

An IUnmanagedBrowsingDatabase to proxy to. The resilient unmanaged database takes ownership of database and will dispose it when the resilient unmanaged database itself is disposed. If you reference or dispose database after you create the resilient unmanaged database, the behavior of the resilient unmanaged database and database is undefined.
Returns
Type Description
ResilientUnmanagedBrowsingDatabase

A resilient unmanaged database.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if database is a null reference.

Create(IUnmanagedBrowsingDatabase, Int32)

Create a Resilient Unmanaged Database.

Declaration
public static ResilientUnmanagedBrowsingDatabase Create(IUnmanagedBrowsingDatabase database, int retryAttempts)
Parameters
Type Name Description
IUnmanagedBrowsingDatabase database

An IUnmanagedBrowsingDatabase to proxy to. The resilient unmanaged database takes ownership of database and will dispose it when the resilient unmanaged database itself is disposed. If you reference or dispose database after you create the resilient unmanaged database, the behavior of the resilient unmanaged database and database is undefined.
System.Int32 retryAttempts

The number of attempts a failed operation should be retried.
Returns
Type Description
ResilientUnmanagedBrowsingDatabase

A resilient unmanaged database.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if database is a null reference.
System.ArgumentOutOfRangeException

Thrown if retryAttempts is less than or equal to 0.

Create(IUnmanagedBrowsingDatabase, Int32, Boolean)

Create a Resilient Unmanaged Database.

Declaration
public static ResilientUnmanagedBrowsingDatabase Create(IUnmanagedBrowsingDatabase database, int retryAttempts, bool ownDatabase)
Parameters
Type Name Description
IUnmanagedBrowsingDatabase database

An IUnmanagedBrowsingDatabase to proxy to.
System.Int32 retryAttempts

The number of attempts a failed operation should be retried.
System.Boolean ownDatabase

A boolean flag indicating whether or not the resilient unmanaged database takes ownership of database and disposes it when the resilient unmanaged database itself is disposed. If the resilient unmanaged database takes ownership of database and you reference or dispose database after you create the resilient unmanaged database, the behavior of the resilient unmanaged database and database is undefined.
Returns
Type Description
ResilientUnmanagedBrowsingDatabase

A resilient unmanaged database.
Exceptions
Type Condition
System.ArgumentNullException

Thrown if database is a null reference.
System.ArgumentOutOfRangeException

Thrown if retryAttempts is less than or equal to 0.

FindThreatListsAsync(String, CancellationToken)

Find Threat Lists Asynchronously.

Declaration
public Task<IReadOnlyCollection<ThreatList>> FindThreatListsAsync(string threatSha256HashPrefix, CancellationToken cancellationToken)
Parameters
Type Name Description
System.String threatSha256HashPrefix

A SHA256 hash prefix, formatted as a hexadecimal encoded string, identifying a threat associated with the collection of ThreatList to retrieve.
System.Threading.CancellationToken cancellationToken

A cancellation token to cancel the asynchronous operation with.
Returns
Type Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<ThreatList>>

A collection of ThreatList the threat identified by threatSha256HashPrefix is associated with. An empty collection indicates no threat lists were found.
Exceptions
Type Condition
BrowsingDatabaseException

Thrown if a database error occurs.
System.ArgumentNullException

Thrown if threatSha256HashPrefix is a null reference.
System.ObjectDisposedException

Thrown if the object is disposed.
System.OperationCanceledException

Thrown if the asynchronous operation is cancelled.

GetThreatListAsync(ThreatListDescriptor, CancellationToken)

Get a Threat List Asynchronously.

Declaration
public Task<ThreatList> GetThreatListAsync(ThreatListDescriptor threatListDescriptor, CancellationToken cancellationToken)
Parameters
Type Name Description
ThreatListDescriptor threatListDescriptor

A ThreatListDescriptor identifying the ThreatList to retrieve.
System.Threading.CancellationToken cancellationToken

A cancellation token to cancel the asynchronous operation with.
Returns
Type Description
System.Threading.Tasks.Task<ThreatList>

The ThreatList identified by threatListDescriptor. A null reference indicates a threat list could not be found.
Exceptions
Type Condition
BrowsingDatabaseException

Thrown if a database error occurs.
System.ArgumentNullException

Thrown if threatListDescriptor is a null reference.
System.ObjectDisposedException

Thrown if the object is disposed.
System.OperationCanceledException

Thrown if the asynchronous operation is cancelled.

GetThreatListsAsync(CancellationToken)

Get Threat Lists Asynchronously.

Declaration
public Task<IReadOnlyCollection<ThreatList>> GetThreatListsAsync(CancellationToken cancellationToken)
Parameters
Type Name Description
System.Threading.CancellationToken cancellationToken

A cancellation token to cancel the asynchronous operation with.
Returns
Type Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<ThreatList>>

A collection of ThreatList. An empty collection indicates no threat lists were found.
Exceptions
Type Condition
BrowsingDatabaseException

Thrown if a database error occurs.
System.ObjectDisposedException

Thrown if the object is disposed.
System.OperationCanceledException

Thrown if the asynchronous operation is cancelled.

GetThreatsAsync(ThreatListDescriptor, CancellationToken)

Get Threats Asynchronously.

Declaration
public Task<IReadOnlyCollection<string>> GetThreatsAsync(ThreatListDescriptor threatListDescriptor, CancellationToken cancellationToken)
Parameters
Type Name Description
ThreatListDescriptor threatListDescriptor

A ThreatListDescriptor identifying the ThreatList the threats that should be retrieved are associated with.
System.Threading.CancellationToken cancellationToken

A cancellation token to cancel the asynchronous operation with.
Returns
Type Description
System.Threading.Tasks.Task<System.Collections.Generic.IReadOnlyCollection<System.String>>

A collection of SHA256 hash prefixes, formatted as hexadecimal encoded strings, identifying the threats that are associated with the ThreatList identified by threatListDescriptor. An empty collection indicates no threats were found.
Exceptions
Type Condition
BrowsingDatabaseException

Thrown if a database error occurs.
System.ArgumentNullException

Thrown if threatListDescriptor is a null reference.
System.ObjectDisposedException

Thrown if the object is disposed.
System.OperationCanceledException

Thrown if the asynchronous operation is cancelled.

Implements

System.IDisposable

Extension Methods