in iothub/device/src/DeviceClient.cs [374:753]
public Task SetReceiveMessageHandlerAsync(
ReceiveMessageCallback messageHandler,
object userContext,
CancellationToken cancellationToken = default) =>
InternalClient.SetReceiveMessageHandlerAsync(messageHandler, userContext, cancellationToken);
/// <summary>
/// Deletes a received message from the device queue.
/// </summary>
/// <param name="lockToken">The message lockToken.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task CompleteAsync(string lockToken) => InternalClient.CompleteAsync(lockToken);
/// <summary>
/// Deletes a received message from the device queue.
/// </summary>
/// <param name="lockToken">The message lockToken.</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="IotHubCommunicationException">Thrown when the operation has been canceled.
/// The inner exception will be <see cref="OperationCanceledException"/>.</exception>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task CompleteAsync(string lockToken, CancellationToken cancellationToken) =>
InternalClient.CompleteAsync(lockToken, cancellationToken);
/// <summary>
/// Deletes a received message from the device queue.
/// </summary>
/// <param name="message">The message.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task CompleteAsync(Message message) => InternalClient.CompleteAsync(message);
/// <summary>
/// Deletes a received message from the device queue.
/// </summary>
/// <param name="message">The message.</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="IotHubCommunicationException">Thrown when the operation has been canceled.
/// The inner exception will be <see cref="OperationCanceledException"/>.</exception>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task CompleteAsync(Message message, CancellationToken cancellationToken) =>
InternalClient.CompleteAsync(message, cancellationToken);
/// <summary>
/// Puts a received message back onto the device queue.
/// </summary>
/// <remarks>
/// The client cannot reject or abandon messages over MQTT protocol. For more details, see
/// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messages-c2d#the-cloud-to-device-message-life-cycle"/>.
/// </remarks>
/// <param name="lockToken">The message lockToken.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task AbandonAsync(string lockToken) => InternalClient.AbandonAsync(lockToken);
/// <summary>
/// Puts a received message back onto the device queue.
/// </summary>
/// <remarks>
/// The client cannot reject or abandon messages over MQTT protocol. For more details, see
/// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messages-c2d#the-cloud-to-device-message-life-cycle"/>.
/// </remarks>
/// <param name="lockToken">The message lockToken.</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="IotHubCommunicationException">Thrown when the operation has been canceled.
/// The inner exception will be <see cref="OperationCanceledException"/>.</exception>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task AbandonAsync(string lockToken, CancellationToken cancellationToken) =>
InternalClient.AbandonAsync(lockToken, cancellationToken);
/// <summary>
/// Puts a received message back onto the device queue.
/// </summary>
/// <remarks>
/// The client cannot reject or abandon messages over MQTT protocol. For more details, see
/// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messages-c2d#the-cloud-to-device-message-life-cycle"/>.
/// </remarks>
/// <param name="message">The message to abandon.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task AbandonAsync(Message message) => InternalClient.AbandonAsync(message);
/// <summary>
/// Puts a received message back onto the device queue.
/// </summary>
/// <remarks>
/// The client cannot reject or abandon messages over MQTT protocol. For more details, see
/// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messages-c2d#the-cloud-to-device-message-life-cycle"/>.
/// </remarks>
/// <param name="message">The message to abandon.</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="IotHubCommunicationException">Thrown when the operation has been canceled.
/// The inner exception will be <see cref="OperationCanceledException"/>.</exception>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task AbandonAsync(Message message, CancellationToken cancellationToken) =>
InternalClient.AbandonAsync(message, cancellationToken);
/// <summary>
/// Deletes a received message from the device queue and indicates to the server that the message could not be processed.
/// </summary>
/// <remarks>
/// The client cannot reject or abandon messages over MQTT protocol. For more details, see
/// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messages-c2d#the-cloud-to-device-message-life-cycle"/>.
/// </remarks>
/// <param name="lockToken">The message lockToken.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task RejectAsync(string lockToken) => InternalClient.RejectAsync(lockToken);
/// <summary>
/// Deletes a received message from the device queue and indicates to the server that the message could not be processed.
/// </summary>
/// <remarks>
/// The client cannot reject or abandon messages over MQTT protocol. For more details, see
/// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messages-c2d#the-cloud-to-device-message-life-cycle"/>.
/// </remarks>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <param name="lockToken">The message lockToken.</param>
/// <exception cref="IotHubCommunicationException">Thrown when the operation has been canceled.
/// The inner exception will be <see cref="OperationCanceledException"/>.</exception>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task RejectAsync(string lockToken, CancellationToken cancellationToken) =>
InternalClient.RejectAsync(lockToken, cancellationToken);
/// <summary>
/// Deletes a received message from the device queue and indicates to the server that the message could not be processed.
/// </summary>
/// <remarks>
/// The client cannot reject or abandon messages over MQTT protocol. For more details, see
/// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messages-c2d#the-cloud-to-device-message-life-cycle"/>.
/// </remarks>
/// <param name="message">The message.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task RejectAsync(Message message) => InternalClient.RejectAsync(message);
/// <summary>
/// Deletes a received message from the device queue and indicates to the server that the message could not be processed.
/// </summary>
/// <remarks>
/// The client cannot reject or abandon messages over MQTT protocol. For more details, see
/// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messages-c2d#the-cloud-to-device-message-life-cycle"/>.
/// </remarks>
/// <param name="message">The message to reject.</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="IotHubCommunicationException">Thrown when the operation has been canceled.
/// The inner exception will be <see cref="OperationCanceledException"/>.</exception>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task RejectAsync(Message message, CancellationToken cancellationToken) =>
InternalClient.RejectAsync(message, cancellationToken);
/// <summary>
/// Sends an event to a hub
/// </summary>
/// <remarks>
/// In case of a transient issue, retrying the operation should work. In case of a non-transient issue, inspect the error
/// details and take steps accordingly.
/// Please note that the list of exceptions is not exhaustive.
/// </remarks>
/// <param name="message">The message to send. Should be disposed after sending.</param>
/// <exception cref="ArgumentNullException">Thrown when a required parameter is null.</exception>
/// <exception cref="TimeoutException">Thrown if the service does not respond to the request within the timeout
/// specified for the operation. The timeout values are largely transport protocol specific. Check the corresponding
/// transport settings to see if they can be configured. The operation timeout for the client can be set using
/// <see cref="OperationTimeoutInMilliseconds"/>.</exception>
/// <exception cref="IotHubCommunicationException">Thrown if the client encounters a transient retriable exception.</exception>
/// <exception cref="IotHubCommunicationException">Thrown when the operation has been canceled. The inner exception will be
/// <see cref="OperationCanceledException"/>.</exception>
/// <exception cref="SocketException">Thrown if a socket error occurs.</exception>
/// <exception cref="WebSocketException">Thrown if an error occurs when performing an operation on a WebSocket connection.</exception>
/// <exception cref="IOException">Thrown if an I/O error occurs.</exception>
/// <exception cref="ClosedChannelException">Thrown if the MQTT transport layer closes unexpectedly.</exception>
/// <exception cref="IotHubException">Thrown if an error occurs when communicating with IoT hub service.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>true</c> then it is a transient exception.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>false</c> then it is a non-transient exception.</exception>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task SendEventAsync(Message message) => InternalClient.SendEventAsync(message);
/// <summary>
/// Sends an event to a hub
/// </summary>
/// <remarks>
/// In case of a transient issue, retrying the operation should work. In case of a non-transient issue, inspect
/// the error details and take steps accordingly.
/// Please note that the list of exceptions is not exhaustive.
/// </remarks>
/// <param name="message">The message to send. Should be disposed after sending.</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="ArgumentNullException">Thrown when a required parameter is null.</exception>
/// <exception cref="OperationCanceledException">Thrown if the service does not respond to the request before the
/// expiration of the passed <see cref="CancellationToken"/>. If a cancellation token is not supplied to the
/// operation call, a cancellation token with an expiration time of 4 minutes is used.
/// </exception>
/// <exception cref="IotHubCommunicationException">Thrown if the client encounters a transient retriable exception. </exception>
/// <exception cref="IotHubCommunicationException">Thrown when the operation has been canceled. The inner exception will be
/// <see cref="OperationCanceledException"/>.</exception>
/// <exception cref="SocketException">Thrown if a socket error occurs.</exception>
/// <exception cref="WebSocketException">Thrown if an error occurs when performing an operation on a WebSocket connection.</exception>
/// <exception cref="IOException">Thrown if an I/O error occurs.</exception>
/// <exception cref="ClosedChannelException">Thrown if the MQTT transport layer closes unexpectedly.</exception>
/// <exception cref="IotHubException">Thrown if an error occurs when communicating with IoT hub service.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>true</c> then it is a transient exception.
/// If <see cref="IotHubException.IsTransient"/> is set to <c>false</c> then it is a non-transient exception.</exception>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task SendEventAsync(Message message, CancellationToken cancellationToken) =>
InternalClient.SendEventAsync(message, cancellationToken);
/// <summary>
/// Sends a batch of events to IoT hub. Use AMQP or HTTPs for a true batch operation. MQTT will just send the messages
/// one after the other.
/// </summary>
/// <param name="messages">A list of one or more messages to send. The messages should be disposed after sending.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task SendEventBatchAsync(IEnumerable<Message> messages) => InternalClient.SendEventBatchAsync(messages);
/// <summary>
/// Sends a batch of events to IoT hub. Use AMQP or HTTPs for a true batch operation. MQTT will just send the messages
/// one after the other.
/// </summary>
/// <param name="messages">An <see cref="IEnumerable{Message}"/> set of message objects.</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="IotHubCommunicationException">Thrown when the operation has been canceled. The inner exception will be
/// <see cref="OperationCanceledException"/>.</exception>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task SendEventBatchAsync(IEnumerable<Message> messages, CancellationToken cancellationToken) =>
InternalClient.SendEventBatchAsync(messages, cancellationToken);
/// <summary>
/// Uploads a stream to a block blob in a storage account associated with the IoTHub for that device.
/// If the blob already exists, it will be overwritten.
/// </summary>
/// <remarks>
/// This API has been deprecated. Users should migrate to the new workflow which involves calling
/// <see cref="GetFileUploadSasUriAsync(FileUploadSasUriRequest, CancellationToken)"/>, using an Azure Storage library
/// of your choice to upload the file, and calling <see cref="CompleteFileUploadAsync(FileUploadCompletionNotification, CancellationToken)"/>.
/// <para>
/// This method uses a very outdated Azure Storage SDK version that is otherwise unused by this client. When users
/// move to the new method, they are in control of the file upload operation and can keep their choice of Azure Storage SDK
/// up to date.
/// </para>
/// </remarks>
/// <param name="blobName">The name of the blob to upload.</param>
/// <param name="source">A stream with blob contents. Should be disposed after upload completes.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
[Obsolete("This API has been split into three APIs: GetFileUploadSasUri, uploading to blob directly using the Azure Storage SDK, and CompleteFileUploadAsync")]
public Task UploadToBlobAsync(string blobName, Stream source) => InternalClient.UploadToBlobAsync(blobName, source);
/// <summary>
/// Uploads a stream to a block blob in a storage account associated with the IoTHub for that device.
/// If the blob already exists, it will be overwritten.
/// </summary>
/// <remarks>
/// This API has been deprecated. Users should migrate to the new workflow which involves calling
/// <see cref="GetFileUploadSasUriAsync(FileUploadSasUriRequest, CancellationToken)"/>, using an Azure Storage library
/// of your choice to upload the file, and calling <see cref="CompleteFileUploadAsync(FileUploadCompletionNotification, CancellationToken)"/>.
/// <para>
/// This method uses a very outdated Azure Storage SDK version that is otherwise unused by this client. When users
/// move to the new method, they are in control of the file upload operation and can keep their choice of Azure Storage SDK
/// up to date.
/// </para>
/// </remarks>
/// <param name="blobName">The name of the blob to upload</param>
/// <param name="source">A stream with blob contents.. Should be disposed after upload completes.</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="OperationCanceledException">Thrown when the operation has been canceled.</exception>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
[Obsolete("This API has been split into three APIs: GetFileUploadSasUri, uploading to blob directly using the Azure Storage SDK, and CompleteFileUploadAsync")]
public Task UploadToBlobAsync(string blobName, Stream source, CancellationToken cancellationToken) =>
InternalClient.UploadToBlobAsync(blobName, source, cancellationToken);
/// <summary>
/// Get a file upload SAS URI which the Azure Storage SDK can use to upload a file to blob for this device
/// See <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-file-upload#initialize-a-file-upload">this documentation for more details</see>.
/// </summary>
/// <param name="request">The request details for getting the SAS URI, including the destination blob name.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
/// <returns>The file upload details to be used with the Azure Storage SDK in order to upload a file from this device.</returns>
public Task<FileUploadSasUriResponse> GetFileUploadSasUriAsync(
FileUploadSasUriRequest request,
CancellationToken cancellationToken = default) =>
InternalClient.GetFileUploadSasUriAsync(request, cancellationToken);
/// <summary>
/// Notify IoT hub that a device's file upload has finished. See
/// <see href="https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-file-upload#notify-iot-hub-of-a-completed-file-upload">this documentation for more details</see>.
/// </summary>
/// <param name="notification">The notification details, including if the file upload succeeded.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task CompleteFileUploadAsync(FileUploadCompletionNotification notification, CancellationToken cancellationToken = default) =>
InternalClient.CompleteFileUploadAsync(notification, cancellationToken);
/// <summary>
/// Sets a new delegate for the named method. If a delegate is already associated with
/// the named method, it will be replaced with the new delegate.
/// </summary>
/// <remarks>
/// A method handler can be unset by passing a null MethodCallback.
/// </remarks>
/// <param name="methodName">The name of the method to associate with the delegate.</param>
/// <param name="methodHandler">The delegate to be used when a method with the given name is called by the cloud service.</param>
/// <param name="userContext">generic parameter to be interpreted by the client code.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task SetMethodHandlerAsync(string methodName, MethodCallback methodHandler, object userContext) =>
InternalClient.SetMethodHandlerAsync(methodName, methodHandler, userContext);
/// <summary>
/// Sets a new delegate for the named method. If a delegate is already associated with
/// the named method, it will be replaced with the new delegate.
/// A method handler can be unset by passing a null MethodCallback.
/// </summary>
/// <param name="methodName">The name of the method to associate with the delegate.</param>
/// <param name="methodHandler">The delegate to be used when a method with the given name is called by the cloud service.</param>
/// <param name="userContext">generic parameter to be interpreted by the client code.</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="OperationCanceledException">Thrown when the operation has been canceled.</exception>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task SetMethodHandlerAsync(
string methodName,
MethodCallback methodHandler,
object userContext,
CancellationToken cancellationToken) =>
InternalClient.SetMethodHandlerAsync(methodName, methodHandler, userContext, cancellationToken);
/// <summary>
/// Sets a new delegate that is called for a method that doesn't have a delegate registered for its name.
/// If a default delegate is already registered it will replace with the new delegate.
/// A method handler can be unset by passing a null MethodCallback.
/// </summary>
/// <param name="methodHandler">The delegate to be used when a method is called by the cloud service and there is
/// no delegate registered for that method name.</param>
/// <param name="userContext">Generic parameter to be interpreted by the client code.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task SetMethodDefaultHandlerAsync(MethodCallback methodHandler, object userContext) =>
InternalClient.SetMethodDefaultHandlerAsync(methodHandler, userContext);
/// <summary>
/// Sets a new delegate that is called for a method that doesn't have a delegate registered for its name.
/// If a default delegate is already registered it will replace with the new delegate.
/// A method handler can be unset by passing a null MethodCallback.
/// </summary>
/// <param name="methodHandler">The delegate to be used when a method is called by the cloud service and there is
/// no delegate registered for that method name.</param>
/// <param name="userContext">Generic parameter to be interpreted by the client code.</param>
/// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
/// <exception cref="OperationCanceledException">Thrown when the operation has been canceled.</exception>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
public Task SetMethodDefaultHandlerAsync(MethodCallback methodHandler, object userContext, CancellationToken cancellationToken) =>
InternalClient.SetMethodDefaultHandlerAsync(methodHandler, userContext, cancellationToken);
/// <summary>
/// Sets a new delegate for the named method. If a delegate is already associated with
/// the named method, it will be replaced with the new delegate.
/// </summary>
/// <param name="methodName">The name of the method to associate with the delegate.</param>
/// <param name="methodHandler">The delegate to be used when a method with the given name is called by the cloud service.</param>
/// <param name="userContext">generic parameter to be interpreted by the client code.</param>
/// <exception cref="ObjectDisposedException">When the client has been disposed.</exception>
[Obsolete("Please use SetMethodHandlerAsync.")]
public void SetMethodHandler(string methodName, MethodCallback methodHandler, object userContext) =>
InternalClient.SetMethodHandler(methodName, methodHandler, userContext);
/// <summary>
/// Sets a new delegate for the connection status changed callback.
/// </summary>
/// <remarks>
/// If a delegate is already associated, it will be replaced with the new delegate. Note that this callback will never be called
/// if the client is configured to use HTTP, as that protocol is stateless.
/// </remarks>
/// <param name="statusChangesHandler">The name of the method to associate with the delegate.</param>
public void SetConnectionStatusChangesHandler(ConnectionStatusChangesHandler statusChangesHandler) =>
InternalClient.SetConnectionStatusChangesHandler(statusChangesHandler);
/// <summary>
/// Releases the unmanaged resources used by the DeviceClient and optionally disposes of the managed resources.
/// </summary>
/// <remarks>
/// The method <see cref="CloseAsync()"/> should be called before disposing.
/// </remarks>
public void Dispose()
{
Dispose(true);
GC.SuppressFinalize(this);
}