src/csharp/Grpc.Core.Api/CallOptions.cs

   1 #region Copyright notice and license
   2
   3 // Copyright 2015 gRPC authors.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the "License");
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16
  17 #endregion
  18
  19 using System;
  20 using System.Threading;
  21
  22 using Grpc.Core.Internal;
  23
  24 namespace Grpc.Core
  25 {
  26     /// <summary>
  27     /// Options for calls made by client.
  28     /// </summary>
  29     public struct CallOptions
  30     {
  31         Metadata headers;
  32         DateTime? deadline;
  33         CancellationToken cancellationToken;
  34         WriteOptions writeOptions;
  35         ContextPropagationToken propagationToken;
  36         CallCredentials credentials;
  37         CallFlags flags;
  38
  39         /// <summary>
  40         /// Creates a new instance of <c>CallOptions</c> struct.
  41         /// </summary>
  42         /// <param name="headers">Headers to be sent with the call.</param>
  43         /// <param name="deadline">Deadline for the call to finish. null means no deadline.</param>
  44         /// <param name="cancellationToken">Can be used to request cancellation of the call.</param>
  45         /// <param name="writeOptions">Write options that will be used for this call.</param>
  46         /// <param name="propagationToken">Context propagation token obtained from <see cref="ServerCallContext"/>.</param>
  47         /// <param name="credentials">Credentials to use for this call.</param>
  48         public CallOptions(Metadata headers = null, DateTime? deadline = null, CancellationToken cancellationToken = default(CancellationToken),
  49                            WriteOptions writeOptions = null, ContextPropagationToken propagationToken = null, CallCredentials credentials = null)
  50         {
  51             this.headers = headers;
  52             this.deadline = deadline;
  53             this.cancellationToken = cancellationToken;
  54             this.writeOptions = writeOptions;
  55             this.propagationToken = propagationToken;
  56             this.credentials = credentials;
  57             this.flags = default(CallFlags);
  58         }
  59
  60         /// <summary>
  61         /// Headers to send at the beginning of the call.
  62         /// </summary>
  63         public Metadata Headers
  64         {
  65             get { return headers; }
  66         }
  67
  68         /// <summary>
  69         /// Call deadline.
  70         /// </summary>
  71         public DateTime? Deadline
  72         {
  73             get { return deadline; }
  74         }
  75
  76         /// <summary>
  77         /// Token that can be used for cancelling the call on the client side.
  78         /// Cancelling the token will request cancellation
  79         /// of the remote call. Best effort will be made to deliver the cancellation
  80         /// notification to the server and interaction of the call with the server side
  81         /// will be terminated. Unless the call finishes before the cancellation could
  82         /// happen (there is an inherent race),
  83         /// the call will finish with <c>StatusCode.Cancelled</c> status.
  84         /// </summary>
  85         public CancellationToken CancellationToken
  86         {
  87             get { return cancellationToken; }
  88         }
  89
  90         /// <summary>
  91         /// Write options that will be used for this call.
  92         /// </summary>
  93         public WriteOptions WriteOptions
  94         {
  95             get { return this.writeOptions; }
  96         }
  97
  98         /// <summary>
  99         /// Token for propagating parent call context.
 100         /// </summary>
 101         public ContextPropagationToken PropagationToken
 102         {
 103             get { return this.propagationToken; }
 104         }
 105
 106         /// <summary>
 107         /// Credentials to use for this call.
 108         /// </summary>
 109         public CallCredentials Credentials
 110         {
 111             get { return this.credentials; }
 112         }
 113
 114         /// <summary>
 115         /// If <c>true</c> and and channel is in <c>ChannelState.TransientFailure</c>, the call will attempt waiting for the channel to recover
 116         /// instead of failing immediately (which is the default "FailFast" semantics).
 117         /// Note: experimental API that can change or be removed without any prior notice.
 118         /// </summary>
 119         public bool IsWaitForReady
 120         {
 121             get { return (this.flags & CallFlags.WaitForReady) == CallFlags.WaitForReady; }
 122         }
 123
 124         /// <summary>
 125         /// Flags to use for this call.
 126         /// </summary>
 127         internal CallFlags Flags
 128         {
 129             get { return this.flags; }
 130         }
 131
 132         /// <summary>
 133         /// Returns new instance of <see cref="CallOptions"/> with
 134         /// <c>Headers</c> set to the value provided. Values of all other fields are preserved.
 135         /// </summary>
 136         /// <param name="headers">The headers.</param>
 137         public CallOptions WithHeaders(Metadata headers)
 138         {
 139             var newOptions = this;
 140             newOptions.headers = headers;
 141             return newOptions;
 142         }
 143
 144         /// <summary>
 145         /// Returns new instance of <see cref="CallOptions"/> with
 146         /// <c>Deadline</c> set to the value provided. Values of all other fields are preserved.
 147         /// </summary>
 148         /// <param name="deadline">The deadline.</param>
 149         public CallOptions WithDeadline(DateTime deadline)
 150         {
 151             var newOptions = this;
 152             newOptions.deadline = deadline;
 153             return newOptions;
 154         }
 155
 156         /// <summary>
 157         /// Returns new instance of <see cref="CallOptions"/> with
 158         /// <c>CancellationToken</c> set to the value provided. Values of all other fields are preserved.
 159         /// </summary>
 160         /// <param name="cancellationToken">The cancellation token.</param>
 161         public CallOptions WithCancellationToken(CancellationToken cancellationToken)
 162         {
 163             var newOptions = this;
 164             newOptions.cancellationToken = cancellationToken;
 165             return newOptions;
 166         }
 167
 168         /// <summary>
 169         /// Returns new instance of <see cref="CallOptions"/> with
 170         /// <c>WriteOptions</c> set to the value provided. Values of all other fields are preserved.
 171         /// </summary>
 172         /// <param name="writeOptions">The write options.</param>
 173         public CallOptions WithWriteOptions(WriteOptions writeOptions)
 174         {
 175             var newOptions = this;
 176             newOptions.writeOptions = writeOptions;
 177             return newOptions;
 178         }
 179
 180         /// <summary>
 181         /// Returns new instance of <see cref="CallOptions"/> with
 182         /// <c>PropagationToken</c> set to the value provided. Values of all other fields are preserved.
 183         /// </summary>
 184         /// <param name="propagationToken">The context propagation token.</param>
 185         public CallOptions WithPropagationToken(ContextPropagationToken propagationToken)
 186         {
 187             var newOptions = this;
 188             newOptions.propagationToken = propagationToken;
 189             return newOptions;
 190         }
 191
 192         /// <summary>
 193         /// Returns new instance of <see cref="CallOptions"/> with
 194         /// <c>Credentials</c> set to the value provided. Values of all other fields are preserved.
 195         /// </summary>
 196         /// <param name="credentials">The call credentials.</param>
 197         public CallOptions WithCredentials(CallCredentials credentials)
 198         {
 199             var newOptions = this;
 200             newOptions.credentials = credentials;
 201             return newOptions;
 202         }
 203
 204         /// <summary>
 205         /// Returns new instance of <see cref="CallOptions"/> with "WaitForReady" semantics enabled/disabled.
 206         /// <see cref="IsWaitForReady"/>.
 207         /// Note: experimental API that can change or be removed without any prior notice.
 208         /// </summary>
 209         public CallOptions WithWaitForReady(bool waitForReady = true)
 210         {
 211             if (waitForReady)
 212             {
 213                 return WithFlags(this.flags | CallFlags.WaitForReady);
 214             }
 215             return WithFlags(this.flags & ~CallFlags.WaitForReady);
 216         }
 217
 218         /// <summary>
 219         /// Returns new instance of <see cref="CallOptions"/> with
 220         /// <c>Flags</c> set to the value provided. Values of all other fields are preserved.
 221         /// </summary>
 222         /// <param name="flags">The call flags.</param>
 223         internal CallOptions WithFlags(CallFlags flags)
 224         {
 225             var newOptions = this;
 226             newOptions.flags = flags;
 227             return newOptions;
 228         }
 229     }
 230 }