-rw-r--r-- | include/opkele/consumer.h | 2 |
1 files changed, 2 insertions, 0 deletions
diff --git a/include/opkele/consumer.h b/include/opkele/consumer.h index b9d1e54..50ff692 100644 --- a/include/opkele/consumer.h +++ b/include/opkele/consumer.h | |||
@@ -1,166 +1,168 @@ | |||
1 | #ifndef __OPKELE_CONSUMER_H | 1 | #ifndef __OPKELE_CONSUMER_H |
2 | #define __OPKELE_CONSUMER_H | 2 | #define __OPKELE_CONSUMER_H |
3 | 3 | ||
4 | #include <opkele/types.h> | 4 | #include <opkele/types.h> |
5 | #include <opkele/extension.h> | 5 | #include <opkele/extension.h> |
6 | 6 | ||
7 | /** | 7 | /** |
8 | * @file | 8 | * @file |
9 | * @brief OpenID consumer-side functionality | 9 | * @brief OpenID consumer-side functionality |
10 | */ | 10 | */ |
11 | 11 | ||
12 | namespace opkele { | 12 | namespace opkele { |
13 | 13 | ||
14 | /** | 14 | /** |
15 | * implementation of basic consumer functionality | 15 | * implementation of basic consumer functionality |
16 | * | 16 | * |
17 | * @note | 17 | * @note |
18 | * The consumer uses libcurl internally, which means that if you're using | 18 | * The consumer uses libcurl internally, which means that if you're using |
19 | * libopkele in multithreaded environment you should call curl_global_init | 19 | * libopkele in multithreaded environment you should call curl_global_init |
20 | * yourself before spawning any threads. | 20 | * yourself before spawning any threads. |
21 | */ | 21 | */ |
22 | class consumer_t { | 22 | class consumer_t { |
23 | public: | 23 | public: |
24 | 24 | ||
25 | virtual ~consumer_t() { } | ||
26 | |||
25 | /** | 27 | /** |
26 | * store association. The function should be overridden in the real | 28 | * store association. The function should be overridden in the real |
27 | * implementation to provide persistent associations store. | 29 | * implementation to provide persistent associations store. |
28 | * @param server the OpenID server | 30 | * @param server the OpenID server |
29 | * @param handle association handle | 31 | * @param handle association handle |
30 | * @param secret the secret associated with the server and handle | 32 | * @param secret the secret associated with the server and handle |
31 | * @param expires_in the number of seconds until the handle is expired | 33 | * @param expires_in the number of seconds until the handle is expired |
32 | * @return the auto_ptr<> for the newly allocated association_t object | 34 | * @return the auto_ptr<> for the newly allocated association_t object |
33 | */ | 35 | */ |
34 | virtual assoc_t store_assoc(const string& server,const string& handle,const secret_t& secret,int expires_in) = 0; | 36 | virtual assoc_t store_assoc(const string& server,const string& handle,const secret_t& secret,int expires_in) = 0; |
35 | /** | 37 | /** |
36 | * retrieve stored association. The function should be overridden | 38 | * retrieve stored association. The function should be overridden |
37 | * in the real implementation to provide persistent assocations | 39 | * in the real implementation to provide persistent assocations |
38 | * store. | 40 | * store. |
39 | * | 41 | * |
40 | * @note | 42 | * @note |
41 | * The user is responsible for handling associations expiry and | 43 | * The user is responsible for handling associations expiry and |
42 | * this function should never return an expired or invalidated | 44 | * this function should never return an expired or invalidated |
43 | * association. | 45 | * association. |
44 | * | 46 | * |
45 | * @param server the OpenID server | 47 | * @param server the OpenID server |
46 | * @param handle association handle | 48 | * @param handle association handle |
47 | * @return the autho_ptr<> for the newly allocated association_t object | 49 | * @return the autho_ptr<> for the newly allocated association_t object |
48 | * @throw failed_lookup if no unexpired association found | 50 | * @throw failed_lookup if no unexpired association found |
49 | */ | 51 | */ |
50 | virtual assoc_t retrieve_assoc(const string& server,const string& handle) = 0; | 52 | virtual assoc_t retrieve_assoc(const string& server,const string& handle) = 0; |
51 | /** | 53 | /** |
52 | * invalidate stored association. The function should be overridden | 54 | * invalidate stored association. The function should be overridden |
53 | * in the real implementation of the consumer. | 55 | * in the real implementation of the consumer. |
54 | * @param server the OpenID server | 56 | * @param server the OpenID server |
55 | * @param handle association handle | 57 | * @param handle association handle |
56 | */ | 58 | */ |
57 | virtual void invalidate_assoc(const string& server,const string& handle) = 0; | 59 | virtual void invalidate_assoc(const string& server,const string& handle) = 0; |
58 | /** | 60 | /** |
59 | * retrieve any unexpired association for the server. If the | 61 | * retrieve any unexpired association for the server. If the |
60 | * function is not overridden in the real implementation, the new | 62 | * function is not overridden in the real implementation, the new |
61 | * association will be established for each request. | 63 | * association will be established for each request. |
62 | * | 64 | * |
63 | * @note | 65 | * @note |
64 | * The user is responsible for handling associations and this | 66 | * The user is responsible for handling associations and this |
65 | * function should never return an expired or invalidated | 67 | * function should never return an expired or invalidated |
66 | * association. | 68 | * association. |
67 | * | 69 | * |
68 | * @param server the OpenID server | 70 | * @param server the OpenID server |
69 | * @return the auto_ptr<> for the newly allocated association_t object | 71 | * @return the auto_ptr<> for the newly allocated association_t object |
70 | * @throw failed_lookup in case of absence of the handle | 72 | * @throw failed_lookup in case of absence of the handle |
71 | */ | 73 | */ |
72 | virtual assoc_t find_assoc(const string& server); | 74 | virtual assoc_t find_assoc(const string& server); |
73 | 75 | ||
74 | /** | 76 | /** |
75 | * retrieve the metainformation contained in link tags from the | 77 | * retrieve the metainformation contained in link tags from the |
76 | * page pointed by url. the function may implement caching of the | 78 | * page pointed by url. the function may implement caching of the |
77 | * information. | 79 | * information. |
78 | * @param url url to harvest for link tags | 80 | * @param url url to harvest for link tags |
79 | * @param server reference to the string object where to put | 81 | * @param server reference to the string object where to put |
80 | * openid.server value | 82 | * openid.server value |
81 | * @param delegate reference to the string object where to put the | 83 | * @param delegate reference to the string object where to put the |
82 | * openid.delegate value (if any) | 84 | * openid.delegate value (if any) |
83 | */ | 85 | */ |
84 | virtual void retrieve_links(const string& url,string& server,string& delegate); | 86 | virtual void retrieve_links(const string& url,string& server,string& delegate); |
85 | 87 | ||
86 | /** | 88 | /** |
87 | * perform the associate request to OpenID server. | 89 | * perform the associate request to OpenID server. |
88 | * @param server the OpenID server | 90 | * @param server the OpenID server |
89 | * @return the auto_ptr<> for the newly allocated association_t | 91 | * @return the auto_ptr<> for the newly allocated association_t |
90 | * object, representing established association | 92 | * object, representing established association |
91 | * @throw exception in case of error | 93 | * @throw exception in case of error |
92 | */ | 94 | */ |
93 | assoc_t associate(const string& server); | 95 | assoc_t associate(const string& server); |
94 | /** | 96 | /** |
95 | * prepare the parameters for the checkid_immediate | 97 | * prepare the parameters for the checkid_immediate |
96 | * request. | 98 | * request. |
97 | * @param identity the identity to verify | 99 | * @param identity the identity to verify |
98 | * @param return_to the return_to url to pass with the request | 100 | * @param return_to the return_to url to pass with the request |
99 | * @param trust_root the trust root to advertise with the request | 101 | * @param trust_root the trust root to advertise with the request |
100 | * @param ext pointer to an extension(s) hooks object | 102 | * @param ext pointer to an extension(s) hooks object |
101 | * @return the location string | 103 | * @return the location string |
102 | * @throw exception in case of error | 104 | * @throw exception in case of error |
103 | */ | 105 | */ |
104 | virtual string checkid_immediate(const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0); | 106 | virtual string checkid_immediate(const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0); |
105 | /** | 107 | /** |
106 | * prepare the parameters for the checkid_setup | 108 | * prepare the parameters for the checkid_setup |
107 | * request. | 109 | * request. |
108 | * @param identity the identity to verify | 110 | * @param identity the identity to verify |
109 | * @param return_to the return_to url to pass with the request | 111 | * @param return_to the return_to url to pass with the request |
110 | * @param trust_root the trust root to advertise with the request | 112 | * @param trust_root the trust root to advertise with the request |
111 | * @param ext pointer to an extension(s) hooks object | 113 | * @param ext pointer to an extension(s) hooks object |
112 | * @return the location string | 114 | * @return the location string |
113 | * @throw exception in case of error | 115 | * @throw exception in case of error |
114 | */ | 116 | */ |
115 | virtual string checkid_setup(const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0); | 117 | virtual string checkid_setup(const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0); |
116 | /** | 118 | /** |
117 | * the actual implementation behind checkid_immediate() and | 119 | * the actual implementation behind checkid_immediate() and |
118 | * checkid_setup() functions. | 120 | * checkid_setup() functions. |
119 | * @param mode checkid_* mode - either mode_checkid_immediate or mode_checkid_setup | 121 | * @param mode checkid_* mode - either mode_checkid_immediate or mode_checkid_setup |
120 | * @param identity the identity to verify | 122 | * @param identity the identity to verify |
121 | * @param return_to the return_to url to pass with the request | 123 | * @param return_to the return_to url to pass with the request |
122 | * @param trust_root the trust root to advertise with the request | 124 | * @param trust_root the trust root to advertise with the request |
123 | * @param ext pointer to an extension(s) hooks object | 125 | * @param ext pointer to an extension(s) hooks object |
124 | * @return the location string | 126 | * @return the location string |
125 | * @throw exception in case of error | 127 | * @throw exception in case of error |
126 | */ | 128 | */ |
127 | virtual string checkid_(mode_t mode,const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0); | 129 | virtual string checkid_(mode_t mode,const string& identity,const string& return_to,const string& trust_root="",extension_t *ext=0); |
128 | /** | 130 | /** |
129 | * verify the id_res response | 131 | * verify the id_res response |
130 | * @param pin the response parameters | 132 | * @param pin the response parameters |
131 | * @param identity the identity being checked (if not specified, | 133 | * @param identity the identity being checked (if not specified, |
132 | * @param ext pointer to an extension(s) hooks object | 134 | * @param ext pointer to an extension(s) hooks object |
133 | * extracted from the openid.identity parameter | 135 | * extracted from the openid.identity parameter |
134 | * @throw id_res_mismatch in case of signature mismatch | 136 | * @throw id_res_mismatch in case of signature mismatch |
135 | * @throw id_res_setup in case of openid.user_setup_url failure | 137 | * @throw id_res_setup in case of openid.user_setup_url failure |
136 | * (supposedly checkid_immediate only) | 138 | * (supposedly checkid_immediate only) |
137 | * @throw id_res_failed in case of failure | 139 | * @throw id_res_failed in case of failure |
138 | * @throw exception in case of other failures | 140 | * @throw exception in case of other failures |
139 | */ | 141 | */ |
140 | virtual void id_res(const params_t& pin,const string& identity="",extension_t *ext=0); | 142 | virtual void id_res(const params_t& pin,const string& identity="",extension_t *ext=0); |
141 | /** | 143 | /** |
142 | * perform a check_authentication request. | 144 | * perform a check_authentication request. |
143 | * @param server the OpenID server | 145 | * @param server the OpenID server |
144 | * @param p request parameters | 146 | * @param p request parameters |
145 | */ | 147 | */ |
146 | void check_authentication(const string& server,const params_t& p); | 148 | void check_authentication(const string& server,const params_t& p); |
147 | 149 | ||
148 | /** | 150 | /** |
149 | * normalize URL by adding http:// and trailing slash if needed. | 151 | * normalize URL by adding http:// and trailing slash if needed. |
150 | * @param url | 152 | * @param url |
151 | * @return normalized url | 153 | * @return normalized url |
152 | */ | 154 | */ |
153 | static string normalize(const string& url); | 155 | static string normalize(const string& url); |
154 | 156 | ||
155 | /** | 157 | /** |
156 | * Canonicalize URL, by normalizing its appearance and following redirects. | 158 | * Canonicalize URL, by normalizing its appearance and following redirects. |
157 | * @param url | 159 | * @param url |
158 | * @return canonicalized url | 160 | * @return canonicalized url |
159 | */ | 161 | */ |
160 | virtual string canonicalize(const string& url); | 162 | virtual string canonicalize(const string& url); |
161 | 163 | ||
162 | }; | 164 | }; |
163 | 165 | ||
164 | } | 166 | } |
165 | 167 | ||
166 | #endif /* __OPKELE_CONSUMER_H */ | 168 | #endif /* __OPKELE_CONSUMER_H */ |