diff options
author | Jon Skeet <skeet@pobox.com> | 2008-08-14 20:35:31 +0100 |
---|---|---|
committer | Jon Skeet <skeet@pobox.com> | 2008-08-14 20:35:31 +0100 |
commit | 3ae573c17475021046f3d3b2b5f01de91c80aa1d (patch) | |
tree | afbb78dc737e949a7aa0da2859d4589ca81ce7fb /csharp/ProtocolBuffers/IRpcController.cs | |
parent | 1e42fdde2ebf34dddf1297bbecc56439ecef323f (diff) | |
download | protobuf-3ae573c17475021046f3d3b2b5f01de91c80aa1d.tar.gz protobuf-3ae573c17475021046f3d3b2b5f01de91c80aa1d.tar.bz2 protobuf-3ae573c17475021046f3d3b2b5f01de91c80aa1d.zip |
Fleshed out service interfaces, and wrote the simpler service tests. Mocking tests still to be done.
Diffstat (limited to 'csharp/ProtocolBuffers/IRpcController.cs')
-rw-r--r-- | csharp/ProtocolBuffers/IRpcController.cs | 80 |
1 files changed, 78 insertions, 2 deletions
diff --git a/csharp/ProtocolBuffers/IRpcController.cs b/csharp/ProtocolBuffers/IRpcController.cs index 81348fde..f4e29ad4 100644 --- a/csharp/ProtocolBuffers/IRpcController.cs +++ b/csharp/ProtocolBuffers/IRpcController.cs @@ -1,8 +1,84 @@ using System; -using System.Collections.Generic; -using System.Text; namespace Google.ProtocolBuffers { + /// <summary> + /// Mediates a single method call. The primary purpose of the controller + /// is to provide a way to manipulate settings specific to the + /// RPC implementation and to find out about RPC-level errors. + /// + /// The methods provided by this interface are intended to be a "least + /// common denominator" set of features which we expect all implementations to + /// support. Specific implementations may provide more advanced features, + /// (e.g. deadline propagation). + /// </summary> public interface IRpcController { + + #region Client side calls + // These calls may be made from the client side only. Their results + // are undefined on the server side (may throw exceptions). + + /// <summary> + /// Resets the controller to its initial state so that it may be reused in + /// a new call. This can be called from the client side only. It must not + /// be called while an RPC is in progress. + /// </summary> + void Reset(); + + /// <summary> + /// After a call has finished, returns true if the call failed. The possible + /// reasons for failure depend on the RPC implementation. Failed must + /// only be called on the client side, and must not be called before a call has + /// finished. + /// </summary> + bool Failed { get; } + + /// <summary> + /// If Failed is true, ErrorText returns a human-readable description of the error. + /// </summary> + string ErrorText { get; } + + /// <summary> + /// Advises the RPC system that the caller desires that the RPC call be + /// canceled. The RPC system may cancel it immediately, may wait awhile and + /// then cancel it, or may not even cancel the call at all. If the call is + /// canceled, the "done" callback will still be called and the RpcController + /// will indicate that the call failed at that time. + /// </summary> + void StartCancel(); + #endregion + + #region Server side calls + // These calls may be made from the server side only. Their results + // are undefined on the client side (may throw exceptions). + + /// <summary> + /// Causes Failed to return true on the client side. <paramref name="reason"/> + /// will be incorporated into the message returned by ErrorText. + /// If you find you need to return machine-readable information about + /// failures, you should incorporate it into your response protocol buffer + /// and should *not* call SetFailed. + /// </summary> + void SetFailed(string reason); + + /// <summary> + /// If true, indicates that the client canceled the RPC, so the server may as + /// well give up on replying to it. This method must be called on the server + /// side only. The server should still call the final "done" callback. + /// </summary> + bool isCanceled(); + + /// <summary> + /// Requests that the given callback be called when the RPC is canceled. + /// The parameter passed to the callback will always be null. The callback will + /// be called exactly once. If the RPC completes without being canceled, the + /// callback will be called after completion. If the RPC has already been canceled + /// when NotifyOnCancel is called, the callback will be called immediately. + /// + /// NotifyOnCancel must be called no more than once per request. It must be + /// called on the server side only. + /// </summary> + /// <param name="callback"></param> + void NotifyOnCancel(Action<object> callback); + #endregion } } |