From 7e67b06f9ba89daa189f280c178d15c5ceb3de10 Mon Sep 17 00:00:00 2001 From: antognolli Date: Wed, 13 Jul 2011 19:04:10 +0000 Subject: [PATCH] ecore/ecore_con - Move more documentation to Ecore_Con.h. Cookie related function documentation is moved, and some additional comments were added to ecore_con_url_cookies_file_add and ecore_con_url_cookies_jar_file_set. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/ecore@61349 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- src/lib/ecore_con/Ecore_Con.h | 142 ++++++++++++++++++++++++++++++++++++++ src/lib/ecore_con/ecore_con_url.c | 115 ------------------------------ 2 files changed, 142 insertions(+), 115 deletions(-) diff --git a/src/lib/ecore_con/Ecore_Con.h b/src/lib/ecore_con/Ecore_Con.h index b2b750e..eb377c1 100644 --- a/src/lib/ecore_con/Ecore_Con.h +++ b/src/lib/ecore_con/Ecore_Con.h @@ -1430,15 +1430,157 @@ EAPI void ecore_con_url_verbose_set(Ecore_Con_Url *url_con, EAPI void ecore_con_url_ftp_use_epsv_set(Ecore_Con_Url *url_con, Eina_Bool use_epsv); +/** + * Enables the cookie engine for subsequent HTTP requests. + * + * @param url_con Ecore_Con_Url instance which will be acted upon. + * + * After this function is called, cookies set by the server in HTTP responses + * will be parsed and stored, as well as sent back to the server in new HTTP + * requests. + * + * @note Even though this function is called @c ecore_con_url_cookies_init(), + * there is no symmetrical shutdown operation. + */ EAPI void ecore_con_url_cookies_init(Ecore_Con_Url *url_con); +/** + * Controls whether session cookies from previous sessions shall be loaded. + * + * @param url_con Ecore_Con_Url instance which will be acted upon. + * @param ignore If @c EINA_TRUE, ignore session cookies when loading cookies + * from files. If @c EINA_FALSE, all cookies will be loaded. + * + * Session cookies are cookies with no expire date set, which usually means + * they are removed after the current session is closed. + * + * By default, when Ecore_Con_Url loads cookies from a file, all cookies are + * loaded, including session cookies, which, most of the time, were supposed + * to be loaded and valid only for that session. + * + * If @p ignore is set to @c EINA_TRUE, when Ecore_Con_Url loads cookies from + * the files passed to @c ecore_con_url_cookies_file_add(), session cookies + * will not be loaded. + * + * @see ecore_con_url_cookies_file_add() + */ EAPI void ecore_con_url_cookies_ignore_old_session_set(Ecore_Con_Url *url_con, Eina_Bool ignore); +/** + * Clears currently loaded cookies. + * @param url_con Ecore_Con_Url instance which will be acted upon. + * + * The cleared cookies are removed and will not be sent in subsequent HTTP + * requests, nor will they be written to the cookiejar file set via + * @c ecore_con_url_cookies_jar_file_set(). + * + * @note This function will initialize the cookie engine if it has not been + * initialized yet. + * @note The cookie files set by ecore_con_url_cookies_file_add() aren't loaded + * immediately, just when the request is started. Thus, if you ask to + * clear the cookies, but has a file already set by that function, the + * cookies will then be loaded and you will have old cookies set. In order + * to don't have any old cookie set, you need to don't call + * ecore_con_url_cookies_file_add() ever on the @p url_con handler, and + * call this function to clear any cookie set by a previous request on + * this handler. + * + * @see ecore_con_url_cookies_session_clear() + * @see ecore_con_url_cookies_ignore_old_session_set() + */ EAPI void ecore_con_url_cookies_clear(Ecore_Con_Url *url_con); +/** + * Clears currently loaded session cookies. + * + * @param url_con Ecore_Con_Url instance which will be acted upon. + * + * Session cookies are cookies with no expire date set, which usually means + * they are removed after the current session is closed. + * + * The cleared cookies are removed and will not be sent in subsequent HTTP + * requests, nor will they be written to the cookiejar file set via + * @c ecore_con_url_cookies_jar_file_set(). + * + * @note This function will initialize the cookie engine if it has not been + * initialized yet. + * @note The cookie files set by ecore_con_url_cookies_file_add() aren't loaded + * immediately, just when the request is started. Thus, if you ask to + * clear the session cookies, but has a file already set by that function, + * the session cookies will then be loaded and you will have old cookies + * set. In order to don't have any old session cookie set, you need to + * don't call ecore_con_url_cookies_file_add() ever on the @p url_con + * handler, and call this function to clear any session cookie set by a + * previous request on this handler. An easier way to don't use old + * session cookies is by using the function + * ecore_con_url_cookies_ignore_old_session_set(). + * + * @see ecore_con_url_cookies_clear() + * @see ecore_con_url_cookies_ignore_old_session_set() + */ EAPI void ecore_con_url_cookies_session_clear(Ecore_Con_Url *url_con); +/** + * Adds a file to the list of files from which to load cookies. + * + * @param url_con Ecore_Con_Url instance which will be acted upon. + * @param file_name Name of the file that will be added to the list. + * + * Files must contain cookies defined according to two possible formats: + * + * @li HTTP-style header ("Set-Cookie: ..."). + * @li Netscape/Mozilla cookie data format. + * + * Cookies will only be @b read from this file. If you want to save cookies to a + * file, use ecore_con_url_cookies_jar_file_set(). Also notice that this + * function supports the both types of cookie file cited above, while + * ecore_con_url_cookies_jar_file_set() will save only in the Netscape/Mozilla's + * format. + * + * Please notice that the file will not be read immediately, but rather added + * to a list of files that will be loaded and parsed at a later time. + * + * @note This function will initialize the cookie engine if it has not been + * initialized yet. + * + * @see ecore_con_url_cookies_ignore_old_session_set() + * @see ecore_con_url_cookies_jar_file_set() + */ EAPI void ecore_con_url_cookies_file_add(Ecore_Con_Url *url_con, const char * const file_name); +/** + * Sets the name of the file to which all current cookies will be written when + * either cookies are flushed or Ecore_Con is shut down. + * + * @param url_con Ecore_Con_Url instance which will be acted upon. + * @param cookiejar_file File to which the cookies will be written. + * + * @return @c EINA_TRUE is the file name has been set successfully, + * @c EINA_FALSE otherwise. + * + * Cookies are written following Netscape/Mozilla's data format, also known as + * cookie-jar. + * + * Cookies will only be @b saved to this file. If you need to read cookies from + * a file, use ecore_con_url_cookies_file_add() instead. + * + * @note This function will initialize the cookie engine if it has not been + * initialized yet. + * + * @see ecore_con_url_cookies_jar_write() + */ EAPI Eina_Bool ecore_con_url_cookies_jar_file_set(Ecore_Con_Url *url_con, const char * const cookiejar_file); +/** + * Writes all current cookies to the cookie jar immediately. + * + * @param url_con Ecore_Con_Url instance which will be acted upon. + * + * A cookie-jar file must have been previously set by + * @c ecore_con_url_jar_file_set, otherwise nothing will be done. + * + * @note This function will initialize the cookie engine if it has not been + * initialized yet. + * + * @see ecore_con_url_cookies_jar_file_set() + */ EAPI void ecore_con_url_cookies_jar_write(Ecore_Con_Url *url_con); EAPI void ecore_con_url_ssl_verify_peer_set(Ecore_Con_Url *url_con, diff --git a/src/lib/ecore_con/ecore_con_url.c b/src/lib/ecore_con/ecore_con_url.c index aec9af1..44de916 100644 --- a/src/lib/ecore_con/ecore_con_url.c +++ b/src/lib/ecore_con/ecore_con_url.c @@ -813,18 +813,6 @@ ecore_con_url_ftp_upload(Ecore_Con_Url *url_con, #endif } -/** - * Enables the cookie engine for subsequent HTTP requests. - * - * After this function is called, cookies set by the server in HTTP responses - * will be parsed and stored, as well as sent back to the server in new HTTP - * requests. - * - * @note Even though this function is called @c ecore_con_url_cookies_init(), - * there is no symmetrical shutdown operation. - * - * @param url_con Ecore_Con_Url instance which will be acted upon. - */ EAPI void ecore_con_url_cookies_init(Ecore_Con_Url *url_con) { @@ -845,26 +833,6 @@ ecore_con_url_cookies_init(Ecore_Con_Url *url_con) #endif } -/** - * Controls whether session cookies from previous sessions shall be loaded. - * - * Session cookies are cookies with no expire date set, which usually means - * they are removed after the current session is closed. - * - * By default, when Ecore_Con_Url loads cookies from a file, all cookies are - * loaded, including session cookies, which, most of the time, were supposed - * to be loaded and valid only for that session. - * - * If @p ignore is set to @c EINA_TRUE, when Ecore_Con_Url loads cookies from - * the files passed to @c ecore_con_url_cookies_file_add(), session cookies - * will not be loaded. - * - * @param url_con Ecore_Con_Url instance which will be acted upon. - * @param ignore If @c EINA_TRUE, ignore session cookies when loading cookies - * from files. If @c EINA_FALSE, all cookies will be loaded. - * - * @see ecore_con_url_cookies_file_add() - */ EAPI void ecore_con_url_cookies_ignore_old_session_set(Ecore_Con_Url *url_con, Eina_Bool ignore) { @@ -886,21 +854,6 @@ ecore_con_url_cookies_ignore_old_session_set(Ecore_Con_Url *url_con, Eina_Bool i #endif } -/** - * Clears currently loaded cookies. - * - * The cleared cookies are removed and will not be sent in subsequent HTTP - * requests, nor will they be written to the cookiejar file set via - * @c ecore_con_url_cookies_jar_file_set(). - * - * @note This function will initialize the cookie engine if it has not been - * initialized yet. - * - * @param url_con Ecore_Con_Url instance which will be acted upon. - * - * @see ecore_con_url_cookies_session_clear() - * @see ecore_con_url_cookies_ignore_old_session_set() - */ EAPI void ecore_con_url_cookies_clear(Ecore_Con_Url *url_con) { @@ -921,24 +874,6 @@ ecore_con_url_cookies_clear(Ecore_Con_Url *url_con) #endif } -/** - * Clears currently loaded session cookies. - * - * Session cookies are cookies with no expire date set, which usually means - * they are removed after the current session is closed. - * - * The cleared cookies are removed and will not be sent in subsequent HTTP - * requests, nor will they be written to the cookiejar file set via - * @c ecore_con_url_cookies_jar_file_set(). - * - * @note This function will initialize the cookie engine if it has not been - * initialized yet. - * - * @param url_con Ecore_Con_Url instance which will be acted upon. - * - * @see ecore_con_url_cookies_clear() - * @see ecore_con_url_cookies_ignore_old_session_set() - */ EAPI void ecore_con_url_cookies_session_clear(Ecore_Con_Url *url_con) { @@ -959,25 +894,6 @@ ecore_con_url_cookies_session_clear(Ecore_Con_Url *url_con) #endif } -/** - * Adds a file to the list of files from which to load cookies. - * - * Files must contain cookies defined according to two possible formats: - * - * @li HTTP-style header ("Set-Cookie: ..."). - * @li Netscape/Mozilla cookie data format. - * - * Please notice that the file will not be read immediately, but rather added - * to a list of files that will be loaded and parsed at a later time. - * - * @note This function will initialize the cookie engine if it has not been - * initialized yet. - * - * @param url_con Ecore_Con_Url instance which will be acted upon. - * @param file_name Name of the file that will be added to the list. - * - * @see ecore_con_url_cookies_ignore_old_session_set() - */ EAPI void ecore_con_url_cookies_file_add(Ecore_Con_Url *url_con, const char * const file_name) { @@ -999,24 +915,6 @@ ecore_con_url_cookies_file_add(Ecore_Con_Url *url_con, const char * const file_n #endif } -/** - * Sets the name of the file to which all current cookies will be written when - * either cookies are flushed or Ecore_Con is shut down. - * - * Cookies are written following Netscape/Mozilla's data format, also known as - * cookie-jar. - * - * @note This function will initialize the cookie engine if it has not been - * initialized yet. - * - * @param url_con Ecore_Con_Url instance which will be acted upon. - * @param cookiejar_file File to which the cookies will be written. - * - * @return @c EINA_TRUE is the file name has been set successfully, - * @c EINA_FALSE otherwise. - * - * @see ecore_con_url_cookies_jar_write() - */ EAPI Eina_Bool ecore_con_url_cookies_jar_file_set(Ecore_Con_Url *url_con, const char * const cookiejar_file) { @@ -1050,19 +948,6 @@ ecore_con_url_cookies_jar_file_set(Ecore_Con_Url *url_con, const char * const co #endif } -/** - * Writes all current cookies to the cookie jar immediately. - * - * A cookie-jar file must have been previously set by - * @c ecore_con_url_jar_file_set, otherwise nothing will be done. - * - * @note This function will initialize the cookie engine if it has not been - * initialized yet. - * - * @param url_con Ecore_Con_Url instance which will be acted upon. - * - * @see ecore_con_url_cookies_jar_file_set() - */ EAPI void ecore_con_url_cookies_jar_write(Ecore_Con_Url *url_con) { -- 2.7.4