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.h2
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
12namespace opkele { 12namespace 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 */