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.h25
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 */
14namespace opkele { 15namespace 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 */