aniani/elinks
1
0
Fork 0
mirror of https://github.com/rkd77/elinks.git synced 2024-12-04 14:46:47 -05:00
Code

Doxygenate src/session/

Browse Source
This commit is contained in:
Kalle Olavi Niemitalo 2007-07-27 03:07:39 +03:00 committed by Kalle Olavi Niemitalo
parent 96176a8c77
commit d5f2d90611
10 changed files with 109 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
src/session/download.c
View File

@ -1,4 +1,5 @@
/* Downloads managment */ /** Downloads managment
* @file */
#ifdef HAVE_CONFIG_H #ifdef HAVE_CONFIG_H
#include "config.h" #include "config.h"
@ -1032,7 +1033,7 @@ tp_save(struct type_query *type_query)
query_file(type_query->ses, type_query->uri, type_query, continue_download, tp_cancel, 1); query_file(type_query->ses, type_query->uri, type_query, continue_download, tp_cancel, 1);
} }
/* This button handler uses the add_dlg_button() interface so that pressing /** This button handler uses the add_dlg_button() interface so that pressing
* 'Show header' will not close the type query dialog. */ * 'Show header' will not close the type query dialog. */
static widget_handler_status_T static widget_handler_status_T
tp_show_header(struct dialog_data *dlg_data, struct widget_data *widget_data) tp_show_header(struct dialog_data *dlg_data, struct widget_data *widget_data)
@ -1045,9 +1046,10 @@ tp_show_header(struct dialog_data *dlg_data, struct widget_data *widget_data)
} }
/* FIXME: We need to modify this function to take frame data instead, as we /** @bug FIXME: We need to modify this function to take frame data
* want to use this function for frames as well (now, when frame has content * instead, as we want to use this function for frames as well (now,
* type text/plain, it is ignored and displayed as HTML). */ * when frame has content type text/plain, it is ignored and displayed
* as HTML). */
void void
tp_display(struct type_query *type_query) tp_display(struct type_query *type_query)
{ {

14
src/session/download.h
View File

@ -27,7 +27,7 @@ struct download {
struct connection *conn; struct connection *conn;
struct cache_entry *cached; struct cache_entry *cached;
/* The callback is called when connection gets into a progress state, /** The callback is called when connection gets into a progress state,
* after it's over (in a result state), and also periodically after * after it's over (in a result state), and also periodically after
* the download starts receiving some data. */ * the download starts receiving some data. */
download_callback_T *callback; download_callback_T *callback;
@ -67,24 +67,24 @@ struct file_download {
int notify; int notify;
struct download download; struct download download;
/* Should the file be deleted when destroying the structure */ /** Should the file be deleted when destroying the structure */
unsigned int delete:1; unsigned int delete:1;
/* Should the download be stopped/interrupted when destroying the structure */ /** Should the download be stopped/interrupted when destroying the structure */
unsigned int stop:1; unsigned int stop:1;
/* Whether to block the terminal when running the external handler. */ /** Whether to block the terminal when running the external handler. */
unsigned int block:1; unsigned int block:1;
/* Whether copiousoutput mode is used by the mailcap entry */ /** Whether copiousoutput mode is used by the mailcap entry */
unsigned int copiousoutput:1; unsigned int copiousoutput:1;
/* The current dialog for this download. Can be NULL. */ /** The current dialog for this download. Can be NULL. */
struct dialog_data *dlg_data; struct dialog_data *dlg_data;
struct listbox_item *box_item; struct listbox_item *box_item;
}; };
/* Stack of all running downloads */ /** Stack of all running downloads */
extern LIST_OF(struct file_download) downloads; extern LIST_OF(struct file_download) downloads;
static inline int static inline int

11
src/session/history.c
View File

@ -1,4 +1,5 @@
/* Visited URL history managment - NOT goto_url_dialog history! */ /** Visited URL history managment - NOT dialog_goto_url() history!
* @file */
#ifdef HAVE_CONFIG_H #ifdef HAVE_CONFIG_H
#include "config.h" #include "config.h"
@ -175,16 +176,16 @@ go_history_by_n(struct session *ses, int n)
go_history(ses, loc); go_history(ses, loc);
} }
/* See go_history() description regarding unpredictable effects on cur_loc() /** Go backward in the history. See go_history() description regarding
* by this function. */ * unpredictable effects on cur_loc() by this function. */
void void
go_back(struct session *ses) go_back(struct session *ses)
{ {
go_history_by_n(ses, -1); go_history_by_n(ses, -1);
} }
/* See go_history() description regarding unpredictable effects on cur_loc() /** Go forward in the history. See go_history() description regarding
* by this function. */ * unpredictable effects on cur_loc() by this function. */
void void
go_unback(struct session *ses) go_unback(struct session *ses)
{ {

13
src/session/history.h
View File

@ -5,13 +5,13 @@ struct location;
struct session; struct session;
struct ses_history { struct ses_history {
/* The first list item is the first visited location. The last list /** The first list item is the first visited location. The last list
* item is the last location in the unhistory. The @current location is * item is the last location in the unhistory. The #current location is
* included in this list. */ * included in this list. */
LIST_OF(struct location) history; LIST_OF(struct location) history;
/* The current location. This is moveable pivot pointing somewhere at /** The current location. This is moveable pivot pointing somewhere at
* the middle of @history. */ * the middle of #history. */
struct location *current; struct location *current;
}; };
@ -24,7 +24,7 @@ void add_to_history(struct ses_history *history, struct location *loc);
void del_from_history(struct ses_history *history, struct location *loc); void del_from_history(struct ses_history *history, struct location *loc);
/* Note that this function is dangerous, and its results are sort of /** Note that this function is dangerous, and its results are sort of
* unpredictable. If the document is cached and is permitted to be fetched from * unpredictable. If the document is cached and is permitted to be fetched from
* the cache, the effect of this function is immediate and you end up with the * the cache, the effect of this function is immediate and you end up with the
* new location being cur_loc(). BUT if the cache entry cannot be used, the * new location being cur_loc(). BUT if the cache entry cannot be used, the
@ -34,7 +34,8 @@ void del_from_history(struct ses_history *history, struct location *loc);
* after call to this function (or the regents go_(un)back(), of course). */ * after call to this function (or the regents go_(un)back(), of course). */
void go_history(struct session *ses, struct location *loc); void go_history(struct session *ses, struct location *loc);
/* Move back -n times if n is negative, forward n times if positive. */ /** Move back -@a n times if @a n is negative, forward @a n times if
* positive. */
void go_history_by_n(struct session *ses, int n); void go_history_by_n(struct session *ses, int n);
void go_back(struct session *ses); void go_back(struct session *ses);

3
src/session/location.c
View File

@ -1,4 +1,5 @@
/* Locations handling */ /** Locations handling
* @file */
#ifdef HAVE_CONFIG_H #ifdef HAVE_CONFIG_H
#include "config.h" #include "config.h"

2
src/session/location.h
View File

@ -16,7 +16,7 @@ struct location {
void copy_location(struct location *, struct location *); void copy_location(struct location *, struct location *);
/* You probably want to call del_from_history() first! */ /** You probably want to call del_from_history() first! */
void destroy_location(struct location *); void destroy_location(struct location *);
#endif #endif

44
src/session/session.c
View File

@ -1,4 +1,5 @@
/* Sessions managment - you'll find things here which you wouldn't expect */ /** Sessions managment - you'll find things here which you wouldn't expect
* @file */
#ifdef HAVE_CONFIG_H #ifdef HAVE_CONFIG_H
#include "config.h" #include "config.h"
@ -64,7 +65,7 @@ struct file_to_load {
struct download download; struct download download;
}; };
/* This structure and related functions are used to maintain information /** This structure and related functions are used to maintain information
* for instances opened in new windows. We store all related session info like * for instances opened in new windows. We store all related session info like
* URI and base session to clone from so that when the new instance connects * URI and base session to clone from so that when the new instance connects
* we can look up this information. In case of failure the session information * we can look up this information. In case of failure the session information
@ -139,7 +140,7 @@ done_saved_session_info(void)
done_session_info(session_info.next); done_session_info(session_info.next);
} }
/* Timer callback for @info->timer. As explained in @install_timer, /** Timer callback for session_info.timer. As explained in install_timer(),
* this function must erase the expired timer ID from all variables. */ * this function must erase the expired timer ID from all variables. */
static void static void
session_info_timeout(int id) session_info_timeout(int id)
@ -440,7 +441,7 @@ load_frames(struct session *ses, struct document_view *doc_view)
} }
} }
/* Timer callback for @ses->display_timer. As explained in @install_timer, /** Timer callback for session.display_timer. As explained in install_timer(),
* this function must erase the expired timer ID from all variables. */ * this function must erase the expired timer ID from all variables. */
void void
display_timer(struct session *ses) display_timer(struct session *ses)
@ -741,7 +742,7 @@ dialog_goto_url_open(void *data)
dialog_goto_url((struct session *) data, NULL); dialog_goto_url((struct session *) data, NULL);
} }
/* Returns 0 if the first session was not properly initialized and /** @returns 0 if the first session was not properly initialized and
* setup_session() should be called on the session as well. */ * setup_session() should be called on the session as well. */
static int static int
setup_first_session(struct session *ses, struct uri *uri) setup_first_session(struct session *ses, struct uri *uri)
@ -821,7 +822,7 @@ setup_first_session(struct session *ses, struct uri *uri)
return 0; return 0;
} }
/* First load the current URI of the base session. In most cases it will just /** First load the current URI of the base session. In most cases it will just
* be fetched from the cache so that the new tab will not appear ``empty' while * be fetched from the cache so that the new tab will not appear ``empty' while
* loading the real URI or showing the goto URL dialog. */ * loading the real URI or showing the goto URL dialog. */
static void static void
@ -991,7 +992,7 @@ encode_session_info(struct string *info,
return info; return info;
} }
/* Older elinks versions (up to and including 0.9.1) sends no magic variable and if /** Older elinks versions (up to and including 0.9.1) sends no magic variable and if
* this is detected we fallback to the old session info format. For this format * this is detected we fallback to the old session info format. For this format
* the magic member of terminal_info hold the length of the URI string. The * the magic member of terminal_info hold the length of the URI string. The
* old format is handled by the default label in the switch. * old format is handled by the default label in the switch.
@ -1000,12 +1001,11 @@ encode_session_info(struct string *info,
* terminal_info data member. The magic variable controls how to interpret * terminal_info data member. The magic variable controls how to interpret
* the fields: * the fields:
* *
* INTERLINK_NORMAL_MAGIC means use the terminal_info session_info * - INTERLINK_NORMAL_MAGIC means use the terminal_info session_info
* variable as an id for a saved session. * variable as an id for a saved session.
* *
* INTERLINK_REMOTE_MAGIC means use the terminal_info session_info * - INTERLINK_REMOTE_MAGIC means use the terminal_info session_info
* variable as the remote session flags. */ * variable as the remote session flags. */
int int
decode_session_info(struct terminal *term, struct terminal_info *info) decode_session_info(struct terminal *term, struct terminal_info *info)
{ {
@ -1279,9 +1279,9 @@ tabwin_func(struct window *tab, struct term_event *ev)
} }
} }
/* /**
* Gets the url being viewed by this session. Writes it into str. * Gets the url being viewed by this session. Writes it into @a str.
* A maximum of str_size bytes (including null) will be written. * A maximum of @a str_size bytes (including null) will be written.
*/ */
unsigned char * unsigned char *
get_current_url(struct session *ses, unsigned char *str, size_t str_size) get_current_url(struct session *ses, unsigned char *str, size_t str_size)
@ -1304,9 +1304,9 @@ get_current_url(struct session *ses, unsigned char *str, size_t str_size)
return safe_strncpy(str, struri(uri), length + 1); return safe_strncpy(str, struri(uri), length + 1);
} }
/* /**
* Gets the title of the page being viewed by this session. Writes it into str. * Gets the title of the page being viewed by this session. Writes it into
* A maximum of str_size bytes (including null) will be written. * @a str. A maximum of @a str_size bytes (including null) will be written.
*/ */
unsigned char * unsigned char *
get_current_title(struct session *ses, unsigned char *str, size_t str_size) get_current_title(struct session *ses, unsigned char *str, size_t str_size)
@ -1323,9 +1323,9 @@ get_current_title(struct session *ses, unsigned char *str, size_t str_size)
return NULL; return NULL;
} }
/* /**
* Gets the url of the link currently selected. Writes it into str. * Gets the url of the link currently selected. Writes it into @a str.
* A maximum of str_size bytes (including null) will be written. * A maximum of @a str_size bytes (including null) will be written.
*/ */
unsigned char * unsigned char *
get_current_link_url(struct session *ses, unsigned char *str, size_t str_size) get_current_link_url(struct session *ses, unsigned char *str, size_t str_size)
@ -1339,9 +1339,9 @@ get_current_link_url(struct session *ses, unsigned char *str, size_t str_size)
return safe_strncpy(str, link->where ? link->where : link->where_img, str_size); return safe_strncpy(str, link->where ? link->where : link->where_img, str_size);
} }
/* get_current_link_name: returns the name of the current link /** get_current_link_name: returns the name of the current link
* (the text between <A> and </A>), str is a preallocated string, * (the text between <A> and </A>), @a str is a preallocated string,
* str_size includes the null char. */ * @a str_size includes the null char. */
unsigned char * unsigned char *
get_current_link_name(struct session *ses, unsigned char *str, size_t str_size) get_current_link_name(struct session *ses, unsigned char *str, size_t str_size)
{ {

84
src/session/session.h
View File

@ -20,7 +20,7 @@ struct terminal;
struct uri; struct uri;
struct window; struct window;
/* Used by delayed_open and delayed_goto_uri_frame. */ /** Used by delayed_open() and delayed_goto_uri_frame(). */
struct delayed_open { struct delayed_open {
struct session *ses; struct session *ses;
struct uri *uri; struct uri *uri;
@ -37,7 +37,7 @@ enum remote_session_flags {
SES_REMOTE_INFO_BOX = 64, SES_REMOTE_INFO_BOX = 64,
}; };
/* This is generic frame descriptor, meaningful mainly for ses_*_frame*(). */ /** This is generic frame descriptor, meaningful mainly for ses_*_frame*(). */
struct frame { struct frame {
LIST_HEAD(struct frame); LIST_HEAD(struct frame);
@ -47,22 +47,22 @@ struct frame {
struct view_state vs; struct view_state vs;
}; };
/* Use for keyboard prefixes. */ /** Use for keyboard prefixes. */
struct kbdprefix { struct kbdprefix {
/* This is the repeat count being inserted by user so far. It is stored /** This is the repeat count being inserted by user so far.
* intermediately per-session. */ * It is stored intermediately per-session. */
int repeat_count; int repeat_count;
#ifdef CONFIG_MARKS #ifdef CONFIG_MARKS
/* If the previous key was a mark prefix, this describes what kind of /** If the previous key was a mark prefix, this describes what kind
* action are we supposed to do when we receive the next key. */ * of action are we supposed to do when we receive the next key. */
enum { KP_MARK_NOTHING, KP_MARK_SET, KP_MARK_GOTO } mark; enum { KP_MARK_NOTHING, KP_MARK_SET, KP_MARK_GOTO } mark;
#endif #endif
}; };
struct session; struct session;
/* This describes, what are we trying to do right now. We pass this around so /** This describes, what are we trying to do right now. We pass this around so
* that we can use generic scheduler routines and when the control will get * that we can use generic scheduler routines and when the control will get
* back to our subsystem, we will know what are we up to. */ * back to our subsystem, we will know what are we up to. */
enum task_type { enum task_type {
@ -104,10 +104,10 @@ struct session_status {
struct led *ecmascript_led; struct led *ecmascript_led;
struct led *popup_led; struct led *popup_led;
#endif #endif
/* Has the tab been visited yet. */ /** Has the tab been visited yet. */
unsigned int visited:1; unsigned int visited:1;
/* Is processing file requests. */ /** Is processing file requests. */
unsigned int processing_file_requests:1; unsigned int processing_file_requests:1;
unsigned int show_tabs_bar_at_top:1; unsigned int show_tabs_bar_at_top:1;
}; };
@ -123,7 +123,7 @@ enum navigate_mode {
NAVIGATE_CURSOR_ROUTING, NAVIGATE_CURSOR_ROUTING,
}; };
/* This is one of the building stones of ELinks architecture --- this structure /** This is one of the building stones of ELinks architecture --- this structure
* carries information about the specific ELinks session. Each tab (thus, at * carries information about the specific ELinks session. Each tab (thus, at
* least one per terminal, in the normal case) has its own session. Session * least one per terminal, in the normal case) has its own session. Session
* describes mainly the current browsing and control state, from the currently * describes mainly the current browsing and control state, from the currently
@ -133,17 +133,20 @@ struct session {
LIST_HEAD(struct session); LIST_HEAD(struct session);
/* The vital session data */ /** @name The vital session data
* @{ */
struct window *tab; struct window *tab;
/* Browsing history */ /** @} @name Browsing history
* @{ */
struct ses_history history; struct ses_history history;
/* The current document */ /** @} @name The current document
* @{ */
LIST_OF(struct file_to_load) more_files; LIST_OF(struct file_to_load) more_files;
@ -158,31 +161,34 @@ struct session {
struct uri *download_uri; struct uri *download_uri;
/* The URI which is the referrer to the current loaded document or NULL /** The URI which is the referrer to the current loaded document
* if there are no referrer. */ * or NULL if there are no referrer.
/* The @referrer members sole purpose is to have the information handy *
* when loading URIs. It is not 'filtered' in anyway at this level only * The @c referrer member's sole purpose is to have the information
* at the lower ones. */ * handy when loading URIs. It is not 'filtered' in anyway at this
* level only at the lower ones. */
struct uri *referrer; struct uri *referrer;
/* The current action-in-progress selector */ /** @} @name The current action-in-progress selector
* @{ */
struct session_task task; struct session_task task;
/* The current browsing state */ /** @} @name The current browsing state
* @{ */
int search_direction; int search_direction;
struct kbdprefix kbdprefix; struct kbdprefix kbdprefix;
int exit_query; int exit_query;
timer_id_T display_timer; timer_id_T display_timer;
/* The text input form insert mode. It is a tristate controlled by the /** The text input form insert mode. It is a tristate controlled by the
* boolean document.browse.forms.insert_mode option. When disabled we * boolean document.browse.forms.insert_mode option. When disabled we
* use modeless insertion and we always insert stuff into the text * use modeless insertion and we always insert stuff into the text
* input field. When enabled it is possible to switch insertion on and * input field. When enabled it is possible to switch insertion on and
* off using ACT_EDIT_ENTER and *_CANCEL. */ * off using ::ACT_EDIT_ENTER and *_CANCEL. */
enum insert_mode insert_mode; enum insert_mode insert_mode;
enum navigate_mode navigate_mode; enum navigate_mode navigate_mode;
@ -191,28 +197,30 @@ struct session {
unsigned char *last_search_word; unsigned char *last_search_word;
/* The possibly running type queries (what-to-do-with-that-file?) */ /** The possibly running type queries (what-to-do-with-that-file?) */
LIST_OF(struct type_query) type_queries; LIST_OF(struct type_query) type_queries;
/* The info for status displaying */ /** The info for status displaying */
struct session_status status; struct session_status status;
/** @} */
}; };
extern LIST_OF(struct session) sessions; extern LIST_OF(struct session) sessions;
extern enum remote_session_flags remote_session_flags; extern enum remote_session_flags remote_session_flags;
/* This returns a pointer to the current location inside of the given session. /** This returns a pointer to the current location inside of the given session.
* That's nice for encapsulation and alrady paid out once ;-). */ * That's nice for encapsulation and already paid out once ;-). */
#define cur_loc(x) ((x)->history.current) #define cur_loc(x) ((x)->history.current)
/* Return if we have anything being loaded in this session already. */ /** Return if we have anything being loaded in this session already. */
static inline int static inline int
have_location(struct session *ses) { have_location(struct session *ses) {
return !!cur_loc(ses); return !!cur_loc(ses);
} }
/* Swaps the current session referrer with the new one passed as @referrer */ /** Swaps the current session referrer with the new one passed as @a referrer.
/* @referrer may be NULL */ * @a referrer may be NULL. */
void set_session_referrer(struct session *ses, struct uri *referrer); void set_session_referrer(struct session *ses, struct uri *referrer);
void void
@ -224,11 +232,11 @@ void process_file_requests(struct session *);
struct string *encode_session_info(struct string *info, struct string *encode_session_info(struct string *info,
LIST_OF(struct string_list_item) *url_list); LIST_OF(struct string_list_item) *url_list);
/* Returns zero if the info was remote sessions or if it failed to create any /** @returns zero if the info was remote sessions or if it failed to
* sessions. */ * create any sessions. */
int decode_session_info(struct terminal *term, struct terminal_info *info); int decode_session_info(struct terminal *term, struct terminal_info *info);
/* Registers a base session and returns it's id. Value <= 0 means error. */ /** Registers a base session and returns its id. Value <= 0 means error. */
int int
add_session_info(struct session *ses, struct uri *uri, struct uri *referrer, add_session_info(struct session *ses, struct uri *uri, struct uri *referrer,
enum cache_mode cache_mode, enum task_type task); enum cache_mode cache_mode, enum task_type task);
@ -249,12 +257,12 @@ struct frame *ses_find_frame(struct session *, unsigned char *);
void free_files(struct session *); void free_files(struct session *);
void display_timer(struct session *ses); void display_timer(struct session *ses);
/* session_is_loading() is like !!get_current_download() but doesn't take /** session_is_loading() is like !!get_current_download() but doesn't take
* @req_sent into account. */ * session.req_sent into account. */
struct download *get_current_download(struct session *ses);
int session_is_loading(struct session *ses); int session_is_loading(struct session *ses);
struct download *get_current_download(struct session *ses);
/* Information about the current document */ /** Information about the current document */
unsigned char *get_current_url(struct session *, unsigned char *, size_t); unsigned char *get_current_url(struct session *, unsigned char *, size_t);
unsigned char *get_current_title(struct session *, unsigned char *, size_t); unsigned char *get_current_title(struct session *, unsigned char *, size_t);
@ -269,7 +277,7 @@ void check_questions_queue(struct session *ses);
unsigned char *get_homepage_url(void); unsigned char *get_homepage_url(void);
/* Returns current keyboard repeat count and reset it. */ /** Returns current keyboard repeat count and reset it. */
int eat_kbd_repeat_count(struct session *ses); int eat_kbd_repeat_count(struct session *ses);
#endif #endif

15
src/session/task.c
View File

@ -1,4 +1,5 @@
/* Sessions task management */ /** Sessions task management
* @file */
#ifdef HAVE_CONFIG_H #ifdef HAVE_CONFIG_H
#include "config.h" #include "config.h"
@ -106,7 +107,7 @@ post_no(void *task_)
done_uri(task->uri); done_uri(task->uri);
} }
/* Check if the URI is obfuscated (bug 382). The problem is said to occur when /** Check if the URI is obfuscated (bug 382). The problem is said to occur when
* a URI designed to pass access a specific location with a supplied username, * a URI designed to pass access a specific location with a supplied username,
* contains misleading chars prior to the @ symbol. * contains misleading chars prior to the @ symbol.
* *
@ -279,13 +280,13 @@ ses_goto(struct session *ses, struct uri *uri, unsigned char *target_frame,
} }
/* If @loaded_in_frame is set, this was called just to indicate a move inside a /** If @a loaded_in_frame is set, this was called just to indicate a move inside
* frameset, and we basically just reset the appropriate frame's view_state in * a frameset, and we basically just reset the appropriate frame's view_state in
* that case. When clicking on a link inside a frame, the frame URI is somehow * that case. When clicking on a link inside a frame, the frame URI is somehow
* updated and added to the files-to-load queue, then ses_forward() is called * updated and added to the files-to-load queue, then ses_forward() is called
* with @loaded_in_frame unset, duplicating the whole frameset's location, then * with @a loaded_in_frame unset, duplicating the whole frameset's location,
* later the file-to-load callback calls it for the particular frame with * then later the file-to-load callback calls it for the particular frame with
* @loaded_in_frame set. */ * @a loaded_in_frame set. */
struct view_state * struct view_state *
ses_forward(struct session *ses, int loaded_in_frame) ses_forward(struct session *ses, int loaded_in_frame)
{ {

4
src/session/task.h
View File

@ -10,8 +10,8 @@ struct terminal;
struct view_state; struct view_state;
struct uri; struct uri;
/* This is for map_selected(), it is used to pass around information about /** This is for map_selected(), it is used to pass around information
* in-imagemap links. */ * about in-imagemap links. */
struct link_def { struct link_def {
unsigned char *link; unsigned char *link;
unsigned char *target; unsigned char *target;