IRpcController.cs 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899
  1. // Protocol Buffers - Google's data interchange format
  2. // Copyright 2008 Google Inc.
  3. // http://code.google.com/p/protobuf/
  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. using System;
  17. namespace Google.ProtocolBuffers {
  18. /// <summary>
  19. /// Mediates a single method call. The primary purpose of the controller
  20. /// is to provide a way to manipulate settings specific to the
  21. /// RPC implementation and to find out about RPC-level errors.
  22. ///
  23. /// The methods provided by this interface are intended to be a "least
  24. /// common denominator" set of features which we expect all implementations to
  25. /// support. Specific implementations may provide more advanced features,
  26. /// (e.g. deadline propagation).
  27. /// </summary>
  28. public interface IRpcController {
  29. #region Client side calls
  30. // These calls may be made from the client side only. Their results
  31. // are undefined on the server side (may throw exceptions).
  32. /// <summary>
  33. /// Resets the controller to its initial state so that it may be reused in
  34. /// a new call. This can be called from the client side only. It must not
  35. /// be called while an RPC is in progress.
  36. /// </summary>
  37. void Reset();
  38. /// <summary>
  39. /// After a call has finished, returns true if the call failed. The possible
  40. /// reasons for failure depend on the RPC implementation. Failed must
  41. /// only be called on the client side, and must not be called before a call has
  42. /// finished.
  43. /// </summary>
  44. bool Failed { get; }
  45. /// <summary>
  46. /// If Failed is true, ErrorText returns a human-readable description of the error.
  47. /// </summary>
  48. string ErrorText { get; }
  49. /// <summary>
  50. /// Advises the RPC system that the caller desires that the RPC call be
  51. /// canceled. The RPC system may cancel it immediately, may wait awhile and
  52. /// then cancel it, or may not even cancel the call at all. If the call is
  53. /// canceled, the "done" callback will still be called and the RpcController
  54. /// will indicate that the call failed at that time.
  55. /// </summary>
  56. void StartCancel();
  57. #endregion
  58. #region Server side calls
  59. // These calls may be made from the server side only. Their results
  60. // are undefined on the client side (may throw exceptions).
  61. /// <summary>
  62. /// Causes Failed to return true on the client side. <paramref name="reason"/>
  63. /// will be incorporated into the message returned by ErrorText.
  64. /// If you find you need to return machine-readable information about
  65. /// failures, you should incorporate it into your response protocol buffer
  66. /// and should *not* call SetFailed.
  67. /// </summary>
  68. void SetFailed(string reason);
  69. /// <summary>
  70. /// If true, indicates that the client canceled the RPC, so the server may as
  71. /// well give up on replying to it. This method must be called on the server
  72. /// side only. The server should still call the final "done" callback.
  73. /// </summary>
  74. bool isCanceled();
  75. /// <summary>
  76. /// Requests that the given callback be called when the RPC is canceled.
  77. /// The parameter passed to the callback will always be null. The callback will
  78. /// be called exactly once. If the RPC completes without being canceled, the
  79. /// callback will be called after completion. If the RPC has already been canceled
  80. /// when NotifyOnCancel is called, the callback will be called immediately.
  81. ///
  82. /// NotifyOnCancel must be called no more than once per request. It must be
  83. /// called on the server side only.
  84. /// </summary>
  85. /// <param name="callback"></param>
  86. void NotifyOnCancel(Action<object> callback);
  87. #endregion
  88. }
  89. }