blob: f3975b36118a2101d17d90dec42e112f0453011c (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
//-----------------------------------------------------------------------
// <copyright file="IDirectWebRequestHandler.cs" company="Outercurve Foundation">
// Copyright (c) Outercurve Foundation. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
namespace DotNetOpenAuth.Messaging {
using System;
using System.Collections.Generic;
using System.Diagnostics.Contracts;
using System.IO;
using System.Net;
using DotNetOpenAuth.Messaging;
using Validation;
/// <summary>
/// A contract for <see cref="HttpWebRequest"/> handling.
/// </summary>
/// <remarks>
/// Implementations of this interface must be thread safe.
/// </remarks>
public interface IDirectWebRequestHandler {
/// <summary>
/// Determines whether this instance can support the specified options.
/// </summary>
/// <param name="options">The set of options that might be given in a subsequent web request.</param>
/// <returns>
/// <c>true</c> if this instance can support the specified options; otherwise, <c>false</c>.
/// </returns>
[Pure]
bool CanSupport(DirectWebRequestOptions options);
/// <summary>
/// Prepares an <see cref="HttpWebRequest"/> that contains an POST entity for sending the entity.
/// </summary>
/// <param name="request">The <see cref="HttpWebRequest"/> that should contain the entity.</param>
/// <returns>
/// The stream the caller should write out the entity data to.
/// </returns>
/// <exception cref="ProtocolException">Thrown for any network error.</exception>
/// <remarks>
/// <para>The caller should have set the <see cref="HttpWebRequest.ContentLength"/>
/// and any other appropriate properties <i>before</i> calling this method.
/// Callers <i>must</i> close and dispose of the request stream when they are done
/// writing to it to avoid taking up the connection too long and causing long waits on
/// subsequent requests.</para>
/// <para>Implementations should catch <see cref="WebException"/> and wrap it in a
/// <see cref="ProtocolException"/> to abstract away the transport and provide
/// a single exception type for hosts to catch.</para>
/// </remarks>
Stream GetRequestStream(HttpWebRequest request);
/// <summary>
/// Prepares an <see cref="HttpWebRequest"/> that contains an POST entity for sending the entity.
/// </summary>
/// <param name="request">The <see cref="HttpWebRequest"/> that should contain the entity.</param>
/// <param name="options">The options to apply to this web request.</param>
/// <returns>
/// The stream the caller should write out the entity data to.
/// </returns>
/// <exception cref="ProtocolException">Thrown for any network error.</exception>
/// <remarks>
/// <para>The caller should have set the <see cref="HttpWebRequest.ContentLength"/>
/// and any other appropriate properties <i>before</i> calling this method.
/// Callers <i>must</i> close and dispose of the request stream when they are done
/// writing to it to avoid taking up the connection too long and causing long waits on
/// subsequent requests.</para>
/// <para>Implementations should catch <see cref="WebException"/> and wrap it in a
/// <see cref="ProtocolException"/> to abstract away the transport and provide
/// a single exception type for hosts to catch.</para>
/// </remarks>
Stream GetRequestStream(HttpWebRequest request, DirectWebRequestOptions options);
/// <summary>
/// Processes an <see cref="HttpWebRequest"/> and converts the
/// <see cref="HttpWebResponse"/> to a <see cref="IncomingWebResponse"/> instance.
/// </summary>
/// <param name="request">The <see cref="HttpWebRequest"/> to handle.</param>
/// <returns>An instance of <see cref="IncomingWebResponse"/> describing the response.</returns>
/// <exception cref="ProtocolException">Thrown for any network error.</exception>
/// <remarks>
/// <para>Implementations should catch <see cref="WebException"/> and wrap it in a
/// <see cref="ProtocolException"/> to abstract away the transport and provide
/// a single exception type for hosts to catch. The <see cref="WebException.Response"/>
/// value, if set, should be Closed before throwing.</para>
/// </remarks>
IncomingWebResponse GetResponse(HttpWebRequest request);
/// <summary>
/// Processes an <see cref="HttpWebRequest"/> and converts the
/// <see cref="HttpWebResponse"/> to a <see cref="IncomingWebResponse"/> instance.
/// </summary>
/// <param name="request">The <see cref="HttpWebRequest"/> to handle.</param>
/// <param name="options">The options to apply to this web request.</param>
/// <returns>An instance of <see cref="IncomingWebResponse"/> describing the response.</returns>
/// <exception cref="ProtocolException">Thrown for any network error.</exception>
/// <remarks>
/// <para>Implementations should catch <see cref="WebException"/> and wrap it in a
/// <see cref="ProtocolException"/> to abstract away the transport and provide
/// a single exception type for hosts to catch. The <see cref="WebException.Response"/>
/// value, if set, should be Closed before throwing.</para>
/// </remarks>
IncomingWebResponse GetResponse(HttpWebRequest request, DirectWebRequestOptions options);
}
}
|
