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