inc/FNetHttpHttpAuthentication.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file                FNetHttpHttpAuthentication.h
  20  * @brief               This is the header file for the %HttpAuthentication class.
  21  *
  22  * This header file contains the declarations of the %HttpAuthentication class.
  23  */
  24
  25 #ifndef _FNET_HTTP_HTTP_AUTHENTICATION_H_
  26 #define _FNET_HTTP_HTTP_AUTHENTICATION_H_
  27
  28 #include <FNetHttpHttpTypes.h>
  29 #include <FNetHttpHttpHeader.h>
  30 #include <FNetHttpHttpMessage.h>
  31 #include <FNetHttpHttpCredentials.h>
  32
  33 namespace Tizen { namespace Net { namespace Http
  34 {
  35 class HttpTransaction;
  36 class _HttpAuthenticationImpl;
  37
  38 /**
  39  * @class       HttpAuthentication
  40  * @brief       This class encapsulates an HTTP authentication.
  41  *
  42  * @since       2.0
  43  *
  44  * The %HttpAuthentication class encapsulates the HTTP authentication activity of the client over the duration of a single transaction.
  45  *
  46  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/net/http_connectivity.htm">HTTP Guide</a>.
  47  *
  48  * The following example demonstrates how to use the %HttpAuthentication class.
  49  *
  50  * @code
  51
  52 #include <FBase.h>
  53 #include <FNet.h>
  54
  55 using namespace Tizen::Base;
  56 using namespace Tizen::Net::Http;
  57
  58 void
  59 MyTransactionEventListener::OnTransactionHeaderCompleted(HttpSession& httpSession, HttpTransaction& httpTransaction, int headerLen, bool authRequired)
  60 {
  61         if (authRequired)
  62         {
  63                 HttpAuthentication* pAuth = httpTransaction.OpenAuthenticationInfoN();
  64                 String basicName("Name");
  65                 String basicpass("Pass");
  66                 HttpCredentials* pCredential = new HttpCredentials(basicName, basicpass);
  67                 String* pRealm = pAuth->GetRealmN();
  68                 NetHttpAuthScheme scheme = pAuth->GetAuthScheme();
  69                 if (scheme == NET_HTTP_AUTH_WWW_BASIC || scheme == NET_HTTP_AUTH_PROXY_BASIC)
  70                 {
  71                         HttpTransaction* pNewTransaction =  pAuth->SetCredentials(*pCredential);
  72                 }
  73         }
  74 }
  75
  76  * @endcode
  77  */
  78 class _OSP_EXPORT_ HttpAuthentication
  79         : public Tizen::Base::Object
  80 {
  81 public:
  82         /**
  83          * This destructor overrides Tizen::Base::Object::~Object().
  84          *
  85          * @since                       2.0
  86          */
  87         ~HttpAuthentication(void);
  88
  89         /**
  90          * Gets the realm value received.
  91          *
  92          * @since                       2.0
  93          * @privlevel           public
  94          * @privilege           http://tizen.org/privilege/http
  95          *
  96          * @return                      The realm value
  97          * @exception           E_SUCCESS                       The method is successful.
  98          * @exception           E_OUT_OF_MEMORY     The memory is insufficient.
  99          * @exception           E_SYSTEM            A system error has occurred.
 100          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 101          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 102          */
 103         Tizen::Base::String* GetRealmN(void) const;
 104
 105         /**
 106          * Gets the authentication scheme received.
 107          *
 108          * @since                       2.0
 109          * @privlevel           public
 110          * @privilege           http://tizen.org/privilege/http
 111          *
 112          * @return                      The authentication scheme, @n
 113          *                                      else @c -1 if an error occurs
 114          * @exception           E_SUCCESS                               The method is successful.
 115          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 116          * @exception           E_SYSTEM                                A system error has occurred.
 117          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 118          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 119          */
 120         NetHttpAuthScheme GetAuthScheme(void) const;
 121
 122         /**
 123          * Sets the credentials required for setting the "WWW-Authenticate" header in the HttpRequest class.
 124          *
 125          * @since                       2.0
 126          * @privlevel           public
 127          * @privilege           http://tizen.org/privilege/http
 128          *
 129          * @return                      The new transaction pointer
 130          * @param[in]           credentials                             The credentials
 131          * @exception           E_SUCCESS                               The method is successful.
 132          * @exception           E_INVALID_STATE                 The method invoked is invalid.
 133          * @exception           E_INVALID_ARG                   The specified input parameter is invalid.
 134          * @exception           E_OUT_OF_MEMORY                 The memory is insufficient.
 135          * @exception           E_SYSTEM                                A system error has occurred.
 136          * @exception           E_AUTHENTICATION                The authentication has failed.
 137          * @exception           E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 138          * @remarks                     This method is used to set the username and password for the given domain and the authentication
 139          *                                      scheme on the reception of the IHttpTransactionEventListener::OnTransactionHeaderCompleted() callback.
 140          *                                      The specific error code can be accessed using the GetLastResult() method.
 141          */
 142         HttpTransaction* SetCredentials(HttpCredentials& credentials);
 143
 144 private:
 145         /**
 146          * This default constructor is intentionally declared as private so that only the platform can create an instance.
 147          */
 148         HttpAuthentication(void);
 149
 150         /**
 151          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 152          *
 153          * @param[in]   rhs     An instance of %HttpAuthentication
 154          */
 155         HttpAuthentication(const HttpAuthentication& rhs);
 156
 157         /**
 158          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 159          *
 160          * @param[in]           rhs                             An instance of %HttpAuthentication
 161          */
 162         HttpAuthentication& operator =(const HttpAuthentication& rhs);
 163
 164 private:
 165         _HttpAuthenticationImpl* __pHttpAuthenticationImpl;
 166         friend class _HttpAuthenticationImpl;
 167
 168 }; // HttpAuthentication
 169
 170 } } } //Tizen::Net::Http
 171 #endif // _FNET_HTTP_HTTP_AUTHENTICATION_H_