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