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          * @exception   E_USER_NOT_CONSENTED            The user blocks an application from calling this method. @b Since: @b 2.1
 102          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 103          */
 104         Tizen::Base::String* GetRealmN(void) const;
 105
 106         /**
 107          * Gets the authentication scheme received.
 108          *
 109          * @since                       2.0
 110          * @privlevel           public
 111          * @privilege           %http://tizen.org/privilege/http
 112          *
 113          * @return                      The authentication scheme, @n
 114          *                                      else @c -1 if an error occurs
 115          * @exception           E_SUCCESS                               The method is successful.
 116          * @exception           E_OUT_OF_MEMORY         The memory is insufficient.
 117          * @exception           E_SYSTEM                                A system error has occurred.
 118          * @exception           E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 119          * @exception   E_USER_NOT_CONSENTED            The user blocks an application from calling this method. @b Since: @b 2.1
 120          * @remarks                     The specific error code can be accessed using the GetLastResult() method.
 121          */
 122         NetHttpAuthScheme GetAuthScheme(void) const;
 123
 124         /**
 125          * Sets the credentials required for setting the "WWW-Authenticate" header in the HttpRequest class.
 126          *
 127          * @since                       2.0
 128          * @privlevel           public
 129          * @privilege           %http://tizen.org/privilege/http
 130          *
 131          * @return                      The new transaction pointer
 132          * @param[in]           credentials                             The credentials
 133          * @exception           E_SUCCESS                               The method is successful.
 134          * @exception           E_INVALID_STATE                 The method invoked is invalid.
 135          * @exception           E_INVALID_ARG                   The specified input parameter is invalid.
 136          * @exception           E_OUT_OF_MEMORY                 The memory is insufficient.
 137          * @exception           E_SYSTEM                                A system error has occurred.
 138          * @exception           E_AUTHENTICATION                The authentication has failed.
 139          * @exception           E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 140          * @exception   E_USER_NOT_CONSENTED            The user blocks an application from calling this method. @b Since: @b 2.1
 141          * @remarks                     This method is used to set the username and password for the given domain and the authentication
 142          *                                      scheme on the reception of the IHttpTransactionEventListener::OnTransactionHeaderCompleted() callback.
 143          *                                      The specific error code can be accessed using the GetLastResult() method.
 144          */
 145         HttpTransaction* SetCredentials(HttpCredentials& credentials);
 146
 147 private:
 148         /**
 149          * This default constructor is intentionally declared as private so that only the platform can create an instance.
 150          */
 151         HttpAuthentication(void);
 152
 153         /**
 154          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 155          *
 156          * @param[in]   rhs     An instance of %HttpAuthentication
 157          */
 158         HttpAuthentication(const HttpAuthentication& rhs);
 159
 160         /**
 161          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 162          *
 163          * @param[in]           rhs                             An instance of %HttpAuthentication
 164          */
 165         HttpAuthentication& operator =(const HttpAuthentication& rhs);
 166
 167 private:
 168         _HttpAuthenticationImpl* __pHttpAuthenticationImpl;
 169         friend class _HttpAuthenticationImpl;
 170
 171 }; // HttpAuthentication
 172
 173 } } } //Tizen::Net::Http
 174 #endif // _FNET_HTTP_HTTP_AUTHENTICATION_H_