file class.boaction.inc.php

function delmov

Discussion: after a message delete or move is handled, this function redirect the browser back to the appropiate page, and puts some data in the URI which the mail_msg class translates into a report to the user recapping what actions just took place. ALSO, note with multiple accounts or with filtering, it may be possible this function is processing a batch of messages that may be from or going to different folders, accounts, and servers. Both here and at the mail_msg move and delete functions, some grouping of message numbers is attempted, but this could be improved upon.

function get_attach

Discussion: Uses the phpgw api browser class to generate the headers which preceed the actual attachment data. Note this is tricky because different browsers, especially the MSIE versions, require different headers to be present in order to handle the data effectively at the clients browser. Incorrect headers can cause things like the browser not getting the name of the attachment, or not starting the associated viewer for the attachment, or even several save_or_open dialogs in a row.

function view_html

Discussion: Used in special cases when simply giving the client browser unprocessed html MIME part(s) is not a good idea or needs special attention. Not a good idea means that there is CSS in the html part which would totally b0rk the look of the clients browser, or certain unusual script. Special Handling means a MULTIPART RELATED message such as Outkrook stationary or Evolutions version of the same, where the html has IMG tags in it that are not real HREFs but rather a reference to another MIME part in the same message. To handle that this message display code swaps that IMG mime part reference with an actual URL used by "get_attach" function to retrieve that particular MIME part from the email server and send it to the browser, this the IMG appears in the HTML message as intended. In that case the processing is done before the message is dispayed, and the processed HTML part is stored as a form hiddenvar in base64 encoded format. The user sees a button saying "View HTML", if clicked this processed HTML part is submitted to this function which base64 decodes it and sends it to the browser as a simgle html page, not a part of a mail like is typical. In either case the user gets that button and the buttons associated form submits data to this function. If the part is not RELATED, i.e. did not require special IMG tag swapping, then this function gets submitted to is a reference to the particular HTML part of the message and it is sent to the browser as a page unto itself. In either case, the part is not displayed inline with other MIME parts, not displayed in the same browser window as the rest of the groupware template, instead this part will be viewed in its own page.

file class.boattach_file.inc.php

function attach UNDER DEVELOPMENT

Discussion: UNDER DEVELOPMENT

file class.bocompose.inc.php

class bocompose

class requires msg_bootstrap object

Discussion: bocompose needs GLOBALS[phpgw]->msg_bootstrap which has function "ensure_mail_msg_exists". Its safe to repeatedly use create_object on it because the api is smart enough not to re-create it if it already exists. And that function "ensure_mail_msg_exists". will not re-create or re-login, so this is "safe".

function get_compose_form_action_url

Discussion: Used by this class and also exposes some usefull functionality, mail.spell uses this function, for example.

function compose

Discussion: ?

file class.bofilters.inc.php

class filter_action_sequence

Discussion: This is how we apply the logic of the "AND" and "OR" that relate the match criteria rows SIMPLE LOGIC: each "and" "or" is compared with the item before it * example: ROW-0: subject contains "you got a raise" ROW-1: AND sender contains "boss" ROW-2: OR sender contains "your brother" * translates to: // (ROW-0 "AND" ROW-1) "OR" ROW-2 if both row 0 and row 1 are not satified, then this particular "logic chain" ends, BUT with row 2, the possible match would be if sender contains "your brother", and this match ALONE triggers the filter action. REMEMBER THIS: *ROW-2 itself can cause a match* because with "(X1 and X2) or X3", X3 alone causes a match. thus satisfying that particular filtes's match criteria and triggering action note: this means this we do *not* have this: // ROW-0 "AND" (ROW-1 "OR" ROW-2) if the above is really what you want: I suggest putting the "OR"s first, which puts the openening and closing Parentheses around the "OR" statement * example: ROW-0: sender contains "boss" ROW-1: OR sender contains "your brother" ROW-0: AND subject contains "you got a raise" * translates to: // (sender contains "boss" -OR- sender contains "your brother") -AND- subject contains "you got a raise" this is how you get the results you want. This example is designed to illustrate the a mail from "boss" about getting a "raise" may be more important to you than a mail from "your brother" with the same subject, because it is possible your brother does not control your compensation and he is just making a joke. You manage this logic by remembering that if you use 3 rows of match criteria, rows one and two have a parentheses around them. Why do it this way? The Sieve concept is to make filters EASY TO UNDERSTAND, studies show people actually use them in such cases therefor the simple rule that ANDs and ORs are paired together in the first and second row, is consistent and hopefully easy enough for "Jane / Joe User" to understand

file class.boindex.inc.php

function get_index_stats_block

Discussion: Different Layouts appear different but use mostly the same source data. Pass param $layout to specify a layout 1or layout 2 style stats appearance, default is "2" which means email layout 2 appearance.

function index_data

Discussion: Not used anymore, if a remote clients wants processed email message list data, this would be the function to use. If necessary it can be updated to produce new data as required. but layout 1 is kinda lame looking, may be replaced.

function mlist_data

file class.bomessage.inc.php

class bomessage

Discussion: takes the complex mime data provided by php, turns it into a flat array with human understandable descriptions of what the parts do,

function bomessage

function message_data

file class.bopreferences.inc.php

class bopreferences

Discussion: NOTE: if prefs are submitted that alter anything relative to a cached data item, the that cached item MUST BE EXPIRED, for example GLOBALS[phpgw]->msg->expire_session_cache_item("mailserver_callstr")

capability initialize class mail_msg object but do not login

Discussion: we need mail_msg fully initialized to set prefs, but we do not need class_dcom, nor do we need to login, this is how to do it:

		$GLOBALS["phpgw"]->msg_bootstrap = CreateObject("email.msg_bootstrap");
			$GLOBALS["phpgw"]->msg_bootstrap->set_do_login(False);
			$GLOBALS["phpgw"]->msg_bootstrap->ensure_mail_msg_exists("name of this calling function", $this->debug_set_prefs);
		

function init_available_prefs

Discussion: This function serves as a single place to establish and maintain all preferences available to the email class. Since the preferenced are stored in a dynamic database, the database schema is not present at the database level, so we define it here. Also, $this->std_prefs[] and $this->cust_prefs[] arrays can be used to build a UI for managing and showing these prefs, and those arrays can be looped through for the setting and storing of these preferences.

		## sample usages of the "init_default" property 
			[init_default] comma seperated, first word is an instructional token
			--possible tokens are--
			string		[any_string]  ex. 'string,new_old'
			set_or_not	[set|not_set]  ex.  'set_or_not,not_set'
			function	[string_will_be_eval'd] ex. 'function,$this->sub_default_userid($accountid)'
			init_no_fill	we will not fill this item during initialization (ex. a password)
			varEVAL	[string_to_eval] ex. "$GLOBALS['phpgw_info']['server']['mail_server']"
		

capability Adding a preference option, HOWTO example.

Discussion: email preferences, like many other phpGW preference items, do not have a Database table devoted only to email preferences. If there were such a Database table, its fields would describe a schema similar to the one we are about to study. Email prefs are stored in the phpGW preferences table, which is shared by many apps and has the charactoristics of a dynamic data store, i.e. we can add, remove, or change email preference details without having to alter the Database table itself. This can make programming easier, but it also can present a chalange if your app has many preferences, which may have a complicted tree-like hierarchy. Low level preference functiond are handled by the pgpGW api. The data itself is stored in the database as a serialized array using the php functions serialize and unserialize. We can gain the flexibility of a rich preference data handling system by doing some work up front. The work in question here is an array based schema hard coded in this function, yet similar schema definitions could exist in an XML file, as the concept is very similar. We use an associaltive array (i,e. not a simple numbered array) to hold our schema data,

		This is a how-to  example for adding an email preference item, saving it to the prefs DB table, 
			retieving the pref, and using it in code. This DocSubTopic deals with adding an email preference item, 
			using pref item "icon theme" as an example. A Step-by-Step example is provided with explanation,
			(1) copy an  existing preference item to use as a template for your new preference item.
			(2) replace in the schema with your information, as such:
			*id*		The "Unique ID" of this pref item. The pref DB uses this like a UID. 
			*type*	[ exists| user_string | known_string ]
			*widget*	[ checkbox | textbox | textarea | combobox | passwordbox ]
			*accts_usage*	[ default, extra_accounts ]
			*write_props*	[ empty_string_ok | password, hidden, encrypted, empty_no_delete | no_db_defang ]
			*lang_blurb*	description displayed to the user on the preferences page.
			*init_default*	--possible tokens are--
						string		[any_string]  ex. 'string,new_old'
						set_or_not	[set|not_set]  ex.  'set_or_not,not_set'
						function		[string_will_be_eval'd] ex. "function,$this->sub_default_userid($accountid)"
						init_no_fill	we will not fill this item during initialization (ex. a password)
						varEVAL		[string_to_eval] ex. "$GLOBALS['phpgw_info']['server']['mail_server']"
			*values*		Array of values available to the user, "key" => "value" , used with combobox widgets.
			*long_desc*	Long help, detained description of the option displayed to the user as "long help".
			(3) Your are done. The preference is now part of email preferences. It will bedisplayed on the preferences 
			page, saved and read from the preferences DB, it will have the default value you specified unless the user 
			chooses otherwise. All this happens automatically, without the developer having to write any more code.
		

function grab_set_prefs_args

function grab_set_prefs_args_gpc

Discussion: For abstraction from phpgw UI and from PHP's GPC data, put the submitted GPC data into a class var $this->args[] array. This array is then used to represent the submitted data, instead of $GLOBALS['HTTP_POST_VARS']. This serves to further seperate the mail functionality from php itself, this function will perform the variable handling of the traditional php page view Get Post Cookie (no cookie data used here though) The same data could be grabbed from any source, XML-RPC for example, insttead of php's GPC vars, so this function could (should) have an equivalent XML-RPC "to handle filling these class variables from an alternative source. These class vars are only relevant to setting email prefs.

concept change in Default Accounts preferences may require Expiring Cached Data

Discussion: EXPIRE ANY CACHED ITEM THAT WAS DERIVED FROM A CHANGED PREF ITEM. We should be precise and only expire if necessary, but for now just expire any cached item that could be effected by a change in preferences. NOTE: default acctnum is always 0, the acctnum which these prefs apply to.

concept change in Extra Accounts preferences may require Expiring Cached Data

Discussion: EXPIRE ANY CACHED ITEM THAT WAS DERIVED FROM A CHANGED PREF ITEM. We should be precise and only expire if necessary, but for now just expire any cached item that could be effected by a change in preferences. NOTE: we locate this after we have obtained a reliable acctnum which these prefs apply to.

function grab_set_prefs_args_xmlrpc

Discussion: functional relative to function "grab_set_prefs_args_gpc()", except this function grabs the data from an alternative, non-php-GPC, source NOT YET IMPLEMENTED

function process_submitted_prefs

Discussion: Reusable function, any preference data structured as in "this->init_available_prefs()" can use this code to automate preference submissions.

function preferences

function process_ex_account_submitted_prefs

function ex_accounts_delete

Discussion: ?

function ex_accounts_edit

function ex_accounts_list

function get_first_empty_ex_acctnum

function obtain_ex_acctnum

file class.bosend.inc.php

class bosend

function get_originating_ip

Discussion: Gets the value for the "X-Originating-IP" header. That header is used by hotmail, for example, it looked like a "good thing" and was a feature request, so we use it here too. Even if the IP private (such as on a LAN), this can still be useful for the admin.

function copy_to_sent_folder

Discussion: If a message has already been sent, and IF the user has set the pref enabling the use of the sent folder, only then should this function be used. If a message has not actually been sent, it should NOT be copied to the "Sent" folder because that misrepresents to the user the history of the message. Mostly this is an issue with automated messages sent from other apps. My .02 cents is that if a user did not send a message by pressing the "Send" button, then the message does not belong in the Sent messages folder. Other people may have a different opinion, so this function will not zap your keyboard if you think differently. Nonetheless, if the user has not enabled the preference "Sent mail copied to Sent Folder", then noting gets copied there no matter what. Note that we obtain these preference settings as shown in the example for this function. If the folder does not already exist, class mail_msg has code to make every reasonable attempt to create the folder automatically. Some servers just do things differently enough (unusual namespaces, sub folder trees) that the auto create may not work, but it is nost likly that it can be created, and even more likely that it already exists. NOTE: this particular class should be made availabllle to public use without the brain damage that is the current learning curve for this code. BUT for now, this is a private function unless you really know what you are doing. Even then, code in this class is subject to change.

capability (FUTURE CODE) append to sent folder without a pre-existing mailsvr_stream.

Discussion: FUTURE CODE what follows is untested but should work to accomplish that. While we do need to login to the mail server, we can just select the INBOX because the IMAP APPEND command does not require you have "selected" the folder that is the target of the append. We should be able to simply bootstrap the msg objext and call login, because during initialization the msg object gathers all the data it can find on what account number we are dealing with here, it handles that for us automatically. We do not want to append to the sent folder of the wrong account.

		## this should work if a stream does not already exist (UNTESTED)
			$this->msg_bootstrap = CreateObject("email.msg_bootstrap");
			$this->msg_bootstrap->ensure_mail_msg_exists('email.bosend.copy_to_sent_folder', $this->debug_send);
			## now run the rest of the function as usual.
		

function sendorspell

Discussion: Compose form submit action target is bosend, naturally, however the spell check button submit is identical EXCEPT "btn_spellcheck" POST var will be set, which requires we handoff the handling to the spell class.

function spellcheck

Discussion: If needed, put the body through stripslashes_gpc() before handing it off to the mail_spell object. This function simply gathers the required information and hands it off to the mail_spell class,

function send

Discussion: advanced function to send mail with all the complexities of modern MIME usage. Currently handles forwarding as an "encapsulated" MIME part, thus prewserving the original messages structure, including any attachments the original message had. Of course the user can attach files, this includes attaching additional files to a forwarded message which itself alsready has attachments.

var msgtype

Discussion: NOTE this is a vestigal way for phpgw apps to inter-operate, I *think* this is being obsoleted via n-tiering and xml-rpc / soap methods. RARELY USED, maybe NEVER used, most email code for this is now commented out "back in the day..." the "x-phpgw" header was specified by a phpgw app *other* than the email app which was used to include special phpgw related handling instructions in the message which to the message intentended to be noticed and processed by the phpgw email app when the user open the mail for viewing, at which time the phpgw email app would issue the special handling instructions contained in the "x-phpgw" header. even before n-tiering of the phpgw apps and api begain, I (angles) considered this a possible area of abuse and I commented out the code in the email app that would notice, process and issue those instructions.

property charset

Discussion: charset could take up a lot of notes here, suffice to say that email began life as a US-ASCII thing and still us-ascii chars are strictly required for some headers, while other headers and the body have various alternative ways to deal with other charsets, ways that are well documented in email and other RFC's and other literature. In the rare event that the phpgw api is unable to provide us with a charset value, we use the RFC specified default value of "US-ASCII"

var from

Discussion: Generally this var does not need to be specified. When the mail is being sent from the user's default email account (or mail on behalf of the user, like automated email notifications), we generate the "from" header for the user, hence no custom "from" arg is necessary. This is the most common scenario, in which case we generate the "from" value as follows: (1) the user's "fullname" (a.k.a. the "personal" part of the address) is always picked up from the phpgw api's value that contains the users name, and (2) the user's email address is either (2a) the default value from the phpgw api which was passed into the user's preferences because the user specified no custom email address preference, or (2b) the user specified a custom email address in the email preferences in which case the aformentioned phpgw api default email address is not used in the user's preferences array, this user supplied value is used instead. Providing a "from" arg is usually for extra email accounts and/or alternative email profiles, where the user wants other than the "from" info otherwise defaultly associated with this email acccount. NOTE: from != sender from is who the mail came from assuming that person is also the mail's author. this is by far the most common scenario, "from" and "author" are usually one in the same (see below for info on when to *also* use "sender" - VERY rare)

var sender

Discussion: RFC2822 makes clear that the Sender header is ONLY used if some one NOT the author (ex. the author's secretary) is sending the author's email. RFC2822 considers that "From" = the author and the "Sender" = the person who clicked the send button. Generally they are one in the same and generally the Sender header (and hence this "sender" var) is NOT needed, not used, not included in the email's headers.

property date

Discussion: According to RFC2822 the Date header *should* be the local time with the correct timezone offset relative to GMT, however this is problematic on many Linux boxen, and in general I have found that reliably extracting this data from the host OS can be tricky, so instead we use a fallback value which is simply GMT time, which is allowed under RFC2822 but not preferred. FUTURE: figure out a host independant way of getting the correct rfc time and TZ offset

property elho SMTP handshake domain value

Discussion: when class.msg_send conducts the handshake with the SMTP server, this will be the required domain value that we supply to the SMTP server. Phpgw is considered the client to the SMTP server. RFC2821 sect 4.1.1.1 specifies this value is almost always the Fully Qualified Domain Name of the SMTP client machine, but rarely, when said client machine has dynamic FQDN or no reverse mapping is available, this value *should* be "address leteral" (see sect 4.1.3). Refer to the documentation for BIND for further reading on reverse lookup issues.

concept 7bit vs. 8bit encoding value in top level headers

Discussion: top level 7bit requires qprinting the body if the body has 8bit chars in it ISSUE 1: "it's unnecessary" nowdays, most all MTAs and IMAP/POP servers can handle 8bit by todays usage, 7bit is quite restrictive, when considering the variety of things that may be attached to or carried in a message (and growing) [begin digression] However, stuffing RFC822 email thru a X500 (?) gateway requires 7bit body, which we could do here, at the MUA level, and may possibly require other alterations of the message that occur at the gateway, some of which may actually drop portions of the message, indeed it's complicated, but rare in terms of total mail volume (?) [end digression] ISSUE 2: "risks violating RFCs and confusing MTAs" setting top level encoding to 7bit when the body actually has 8bit chars is "TOTALLY BAD" MTA's will be totally confused by that mis-match, and it violates RFCs **More Importantly** this is a coding and functionality issue involved in forwarding: in general, when you forward a message you should not alter that message if that forwarded message has 8bit chars, I don't think that can be altered even to quote-print that forwarded part (i.e. to convert it to 7bit) would be altering it I suppose you could base64 encode it, on the theory that it decodes exactly back into it's original form, but the practice of base64 encoding non-attachments (i.e. text parts) is EXTREMELY rare in my experience (Angles) and still problematic in coding for this. I suppose this assumes qprint is possible "lossy" in that the exact original may not be exactly the same as said pre-encoded forwarded part, and, after all, it's still altering the part. CONCLUSION: Set Top Level Header "Content-Transfer-Encoding" to "8bit" because it's easier to code for and less likely to violate RFCs. for now send out as 8bit and hope for the best.

file class.html_widgets.inc.php

class html_option

Discussion: used in making select text, value items, such as in the combobox widget.

class hiddenvar_option

Discussion: ?

class html_widgets

Discussion: OOP style class for producing common widgets in html pages, such as a combobox. Designed to reduce bain damage to the developer by hiding the details of the html tags and by treating these things as widgets which is what they are, more than just simple html markup.

class requires including spell_struct header file

Discussion: class html_widgets needs the special C-Style Include .h like file, class.spell_struct which holds data structure class correction_info used here for integration with the mail.spell spellchecking class.

capability HREF LINK WIDGET

Discussion: generate an a href item, includes link, target, text. CLEARS ITSELF after each "get_href"

		$this->widgets->set_href_link('index.php');
		$this->widgets->set_href_target('top');
		$this->widgets->get_href_clickme(lang('click here for more info in a new window'));
		$my_href_tag = $this->widgets->get_href();
		

function clear_href_vars

Discussion: href class vars for link, target, text. CLEARS ITSELF after each "get_href". This utilty function does that. It is RARE that you would ever need to call this directly.

function set_href_link

function get_href_link

function set_href_target

function get_href_target

function set_href_clickme

function get_href_clickme

function get_href

Discussion: After you set "href_target", "href_clickme" and other optional properties ("href_target") this function generates an HREF tag from that data and returns it. NOTE after generating the HREF tag, and before returning it, this function CLEARS ALL PROPERTIES that it used to make that href tag, so this "widget" automatically is ready to new usage without having to explicitly call any "new" or "clear" function.

function href_maketag (not related to the HREF widget)

Discussion: not really a widget, does not use OOP style, but it gets the job done quickly. Somewhat Depreciated, use the OOP style href widget instead.

		this->href_maketag("index.jsp", "click here for home page", "new");
		

function img_maketag

Discussion: not really a widget but it gets the job done. QUICK way to generate a typical A IMG html item in a single function call. Not OOP style, just a quick utilty function. ALL params must be passed in this function call.

		$my_img = widgets->img_maketag("poweredby.png", "powered by RedHat",  "", "", "0");
		

capability COMBOBOX WIDGET

Discussion: generate a combo box html widget.

		$this->widgets->new_combobox();
		$this->widgets->set_cbox_name("user_choice");
		$this->widgets->set_cbox_item("yes"', "Customer is Right");
		$this->widgets->set_cbox_item("no"', "Customer is Wrong");
		$my_combobox_wirget = $this->widgets->get_combobox();
		

function set_cbox_name

function get_cbox_name

function set_cbox_onChange

function get_cbox_onChange

function set_cbox_item

function set_cbox_item_spellcheck

Discussion: This function makes use of structure "correction_info" which we expose by including file class.spell_struct in the constructor for this class. The combobox select item this function makes embeds array data in the items "value" by setting it to a string that resembles a URL get request, which we then can recover this array by applying php function parse_str to the value when the user submits the form. The idea is to provide enough data in the value that the spellcheck replacement code can accurately find and replace the desired word, or not change the word at all if special suggestion string "K_E_E_P" is present. The first suggestion should be en empty string with special value "K_E_E_P" which means no change to the misspelled word, this is indicated by passing an empty string for param $suggestion_num. The value for the suggestion item is a URL type string that contains as much informaion as we can preserve from the $this_bad_word_element object param, but specifying the individual suggestion provieded by the $suggestion_num arg which is the index to this particular suggestion in the $this_bad_word_element->suggestions[] numbered array of suggestions. Upon submit, we can apply php function parse_str() to this uri to recover the desired array structure. Parse_str will even urldecode the items for us.

function get_cbox_item

function new_combobox

function get_combobox

Discussion: this function does not clear its properties, so if for some reason you want THE SAME comboboxes more then one time, calling "get_combobox" will return the same combobox until you clear it by calling "new_combobox", which you should ALWAYS do when starting a new combobox widget.

capability FORM WIDGET

Discussion: generate a opening tag of a form including name, action, method, and hiddenvars

		$this->widgets->new_form();
		$this->widgets->set_form_name('spell_review');
		$this->widgets->set_form_method('POST');
		$this->widgets->set_form_action('index.php?email.targets.move');
		$this->widgets->set_form_hiddenvar('subject', 'stock');
		$this->widgets->set_form_hiddenvar('symbol', 'GM');
		// OPTIONAL if you have set "preserve_vars" you can include them as hidden vars with this command
		$this->commit_preserve_vars_to_form();
		$my_form_tag = $this->widgets->get_form();
		

function set_form_name

function get_form_name

function set_form_action

function

function set_form_method

function get_form_method

function set_form_hiddenvar

function get_form_hiddenvar

function get_form

function form_closetag

Discussion: This seems dumb at first, but take the folders combobox as an example, when the user selects a folder from the combbox the OnChange submits the form associated with that combobox, i.e. the form OnChange and the form name should be the same name and the form age should surround the combobox, I think, Anyway, IMAP servers have folders but POP servers do now, so we will not show said folder combobox if viewing a POP3 mail server. Therefor, in our template we put a non-breaking-space in the place of the combobox html. BUT what about that those form tage that surround this combobox, we should leave them out too. In typical templaying this is ease to replace the form opening tag with a non-breaking-space. BUT the closing tag is such a simple thing we often hard code it into the template, not a template var. SO we can not leave out the form open tag but have the form close tag still be in the template. This no-brainer function just makes it easy to remember to leave out or include, as the case may be, the form closeing tag.

function make_button

Discussion: Since a button is generally considered a "widget", I will call this a widget although it does not use "set_" property functions the other widgets do. All params must be passed in the function call.

		$my_button = $this->widgets->make_button('submit', 'btn_send', lang('Send'));
		

capability TOOLBAR COMPOUND WIDGET

Discussion: generate a toolbar for use in email pages NOTE: usually only one toolbar made per page view so there is no "new_toolbar" function because we should not need it. set_toolbar_msg is the only value that you might want to check if you make more then one toolbar.

function set_toolbar_msg

Discussion: Usually after deleting or moving messages or creating, renaming, or deleting folders, the mail_msg generates some kind of message to report to the user what actions were just taken. Note a blank string will clear a msg if needed. Currently only the uiindex page and the uifolder page might provide a msg.

function get_toolbar_msg

function get_toolbar

Discussion: generate a toolbar for use in email pages NOTE: WE NEED globals[phpge]->msg OBJECT and A LOGIN in order to make this toolbar, THEREFOR do not put this toolbar on a page where login may not be available.Currently, Preferencs pages DO NOT LOGIN, because if you are setting preferences you do not need a mailserver stream AND you may not even have enough data set to get a mailserver stream. Note: uses a private template object to assemple the toolbar, calling function is responsible for putting the result in the global template.

function all_folders_combobox

Discussion: The first item in this folder combo box tells the user to "pick a folder to change to", and has no "value", the value is an empty string, this is more like a label than a combobox item.

function all_accounts_combobox

Discussion: the "values" are in the form of a URI request string, since a combobox can only submit a single string as its value. This way we put alot of information if the form of the URI request and use php function "parse_str" to "recover" all this data on the submit. Accounts have a "status" associated with them, can be "enabled", "disabled", or "empty". In this combobox we show "enabled" and "disabled" accounts, not "empty" accounts. NOTE "disabled" really has no use, and "empty" I am not sure if that is ever used anywhere at all. Also note that a "disabled" account should never be "pre-selected" in this combobox, which seems logical. Almost always there is an email account that can be considered "active" because the user is viewing its data (folders, messages, its preferences) or if the user is composing a message then the last "active" account is considered the account which this mail will be "from". Therefor, generally all mail activity have an account that it applies to. So when this combobox comes across the account that is currently "active", that account will be "pre-selected" in the combobox. This serves two purposes, ONE, the user can not swicth to an account that is currently the "active" account, the user can only switch do a different account, and TWO, this gives the user visual feedback about which account is currently "active", on some pages, such as the compose page, this remines the user who the mail will be "from", i.e. which account sent the mail. In making this thing we iterate thru the "extra_and_default_acounts list", which is an numbered array whose members are structured array data describing the account.

file class.mail_dcom.inc.php

class MAIL_DCOM

Discussion: php may or may not have IMAP extension built in. This class will AUTO-DETECT that and load either (a) a class which mostly wraps the available builtin functions, or (b) a TOTAL REPLACEMENT to PHPs builtin imap extension. Currently, the POP3 socket class is fully implemented, basically a re-write of the UWash c-client, because all the logic contained in an imap server had to be emulated locally here, since a pop server provides only the most basic information, the rest must be deduced. NOTE: the imap socket class is NOT COMPLETE!

file class.mail_dcom_base.inc.php

function utf7_encode

function utf7_encode_string

function utf7_decode

function utf7_decode_string

function get_flag

file class.mail_dcom_base_sock.inc.php

class mailbox_status (sockets)

Discussion: see PHP function: IMAP_STATUS -- This function returns status information on a mailbox other than the current one SA_MESSAGES - set status->messages to the number of messages in the mailbox SA_RECENT - set status->recent to the number of recent messages in the mailbox SA_UNSEEN - set status->unseen to the number of unseen (new) messages in the mailbox SA_UIDNEXT - set status->uidnext to the next uid to be used in the mailbox SA_UIDVALIDITY - set status->uidvalidity to a constant that changes when uids for the mailbox may no longer be valid SA_ALL - set all of the above

class mailbox_msg_info (sockets)

Discussion: see PHP function: IMAP_MAILBOXMSGINFO -- Get information about the current mailbox

		structure returns this data
	Date		date of last change
	Driver		driver
	Mailbox	name of the mailbox
	Nmsgs	number of messages
	Recent		number of recent messages
	Unread	number of unread messages
	Deleted	number of deleted messages
	Size		mailbox size
		

class mailbox_status (sockets) discussion VS. class mailbox_msg_info (sockets)

Discussion: class mailbox_status is used by function IMAP_STATUS class mailbox_msg_info is used by function IMAP_MAILBOXMSGINFO These two functions / classes are similar, some notes on their usage is the example below

		Note 1)
	IMAP_MAILBOXMSGINFO is only used for the folder that the client is currently logged into,
	for pop3 this is always "INBOX", for imap this is the currently selected (opened) folder.
	Therefor, with imap the target folder must already be selected (via IMAP_OPEN or IMAP_REOPEN)
	Note 2)
	IMAP_STATUS is can be used to obtain data on a folder that is NOT currently selected (opened)
	by the client. For pop3 this difference means nothing, for imap this means the client
	need NOT select (i.e. open) the target folder before requesting status data.
	Still, IMAP_STATUS can be used on any folder wheter it is currently selected (opened) or not.
	Note 3)
	The main functional difference is that one function returns size data, and the other does not.
	imap_mailboxmsginfo returns size data, imap_status does NOT.
	This size data adds all the sizes of the messages in that folder together to get the total folder size.
	Some IMAP servers can take alot of time and CPU cycles to get this total,
	particularly with MAILDIR type imap servers such as Courier-imap, while other imap servers
	seem to return this size data with little difficulty.
		

class msg_structure (sockets)

Discussion: see PHP function: imap_fetchstructure -- Read the structure of a particular message

		structure of return data is this
	type			Primary body type
	encoding		Body transfer encoding
	ifsubtype		TRUE if there is a subtype string
	subtype		MIME subtype
	ifdescription		TRUE if there is a description string
	description		Content description string
	ifid			TRUE if there is an identification string
	id			Identification string
	lines			Number of lines
	bytes			Number of bytes
	ifdisposition		TRUE if there is a disposition string
	disposition		Disposition string
	ifdparameters		TRUE if the dparameters array exists
	dparameters		Disposition parameter array
	ifparameters		TRUE if the parameters array exists
	parameters		MIME parameters array
	parts			Array of objects describing each message part
		

class msg_overview (sockets)

Discussion: see PHP function: imap_fetch_overview -- Read an overview of the information in the headers of the given message. NOT CURRENTY IMPLEMENTED

class hdr_info_envelope (sockets)

Discussion: see PHP function: imap_headerinfo -- Read the header of the message see PHP function: imap_header which is simply an alias to imap_headerinfo

class mail_dcom_base (sockets)

Discussion: mail_dcom_base Extends phpgw api class network After mail_dcom_base is loaded, a top level class mail_dcom is created specifically for the necessary propocol, either POP3, IMAP, or NNTP

		CreateObject('email.mail_dcom');
		

function error

function get_flag

function distill_fq_folder

		this is the array return struture
		result['folder'] : string is the folder (a.k.a. mailbox) name WITHOUT the bracketed 
		result['svr_and_port'] string : for Internal Use
		result['server'] : string is the IP or NAME of the server
		result['port_with_junk'] string : for Internal Use
		result['port'] string is the port number
		

Discussion: $fq_folder name arrives as: FOLDERNAME OR some variation like this: FOLDERNAME FOLDERNAME this is how php passes around this data in its builtin IMAP extensions this function breaks down that string into it's parts

function read_port_glob

Discussion: POP3 servers data typically ends with special charactor(s), usually an empty line, i.e. a lone CRLF pair, or line that is a period "." followed br a CRLF pair thus we can direct this function to read the server's data until such special end flag is reached

function glob_to_array

Discussion: ?

function show_crlf

Discussion: useful for debugging, CRLF pairs are CarrageReturn + LineFeed which is the standard way email client and servers end any line while communicating

function phpGW_quoted_printable_decode

Discussion: PHP `quoted_printable_decode` function does not work properly: it should convert '_' characters into ' '.

function phpGW_quoted_printable_decode2

Discussion: Remove '=' at the end of the lines. `quoted_printable_decode` doesn't do it.

function decode_base64

Discussion: uses ereg_replace and preg_replace in addition to php function base64_decode

function decode_qp

Discussion: ?

function decode_header

Discussion: ?

function decode_author

Discussion: ?

function get_mime_type

Discussion: useable but depreciated

function type_int_to_str

Discussion: ?

function get_mime_encoding

Discussion: ?

function encoding_int_to_str

Discussion: ?

function get_att_name

Discussion: usable but depreciated

function uudecode

Discussion: appears to implement UUDECODE without any special php functions.

file class.mail_dcom_imap_sock.inc.php

function str_begins_with

Discussion: this is a NON-REGEX way to to so this, and is NOT case sensitive this *should* be faster then Regular expressions and *should* not be confused by regex special chars such as the period "." or the slashes "/" and "\" , etc...

		?
		

function imap_read_port

Discussion: IMAP servers send out data that is fairly well "typed", meaning RFC2060 is pretty strict about what the server may send out, allowing the client (us) to more easily interpet this data. The important indicator is the string at the beginning of each line of data from the server, it can be: "*" (astrisk) = "untagged" = means "this line contains server data and more data will follow" "+" (plus sign) means "you, the client, must now finish sending your data to the server" "tagged" is the command tag that the client used to initiate this command, such as "A001" IMAP server's final line of data for that command will contain that command's tag as sent from the client This tagged "command completion" signal is followed by either: "OK" = successful command completion "NO" = failure of some kind "BAD" = protocol error such as unrecognized command or syntax error, client should abort this command processing

		?
		

function report_svr_data

function server_last_error

Discussion: ?

		?
		

function open

Discussion: implements the functionality of php function IMAP_OPEN note that php's IMAP_OPEN applies to IMAP, POP3 and NNTP servers

		?
		

function reopen

Discussion: ?

function listmailbox

function status

Discussion: implements the functionality of php function IMAP_STATUS

		?
		

function get_body

file class.mail_dcom_pop3_sock.inc.php

class mail_dcom (sockets)

Discussion: mail_dcom Extends mail_dcom_base which Extends phpgw api class network This is a top level class mail_dcom is designed specifically POP3

		CreateObject('email.mail_dcom');
		

function createmailbox

function deletemailbox

function expunge

function listmailbox

function mailcopy

function mail_move

function reopen

function append

function fetch_overview

function noop_ping_test

function server_last_error

function open

Discussion: implements the functionality of php function IMAP_OPEN note that php IMAP_OPEN applies to IMAP, POP3 and NNTP servers

function close

Discussion: implements the functionality of php function IMAP_CLOSE, note that with POP3, messages are marked "Deleted" and then automatically expunged on QUIT, aka IMAP_CLOSE.

function mailboxmsginfo

Discussion: implements php function IMAP_MAILBOXMSGINFO

function status

Discussion: needed

function num_msg

Discussion: actually usrs the function ->mailboxmsginfo to obtain the return data

function sort

Discussion: using SORTDATE can cause some messages to be displayed in the wrong cronologicall order, because the sender's MUA can be innaccurate in date stamping

		param criteria is used like this
		SORTDATE 0 This is the Date that the senders email client stamps the message with
		SORTARRIVAL 1  This is the date the email arrives at your email server (MTA)
		SORTFROM  2
		SORTSUBJECT 3
		SORTSIZE  6
		

function fetch_header_element

function fetchstructure

Discussion: basiclly a replacement for PHPs c-client logic which is missing if IMAP is not builtin

function fill_toplevel_fetchstructure

Discussion: basiclly a replacement for PHP's c-client logic which is missing if IMAP is not builtin

function create_embeded_fetchstructure

Discussion: as implemented, reference is to some part of class var $this->msg_structure

function sub_get_structure

Discussion: as implemented, reference is to some part of class var $this->msg_structure

function unset_unfilled_fetchstructure

Discussion: as implemented, reference is to some part of class var $this->msg_structure unsets any unfilled elements of the referenced part in the fetchstructure object to mimic PHPs return structure

function parse_type_subtype

Discussion: as implemented, reference is to some part of class var $this->msg_structure parses "content-type:" header into fetchstructure data ->type and ->subtype

function parse_msg_params

Discussion: as implemented, reference is to some part of class var $this->msg_structure parses "content-type:" header string into fetchstructure data info->parameters or "content-disposition:" header string into fetchstructure data info->dparameters

function type_str_to_int

function default_type

function default_subtype

function default_encoding

function more_info

function encoding_str_to_int

function size_msg

function header

Discussion: none

function get_addr_details

Discussion: none

function delete

Discussion: Similar to an IMAP server, POP3 must be expunged to actually delete marked messages This is done (1) by immediately closing the connection after your done marking, this will cause POP3 to expunge or (2) by issuing PHPs buildin IMAP_EXPUNGE command which we DO NOT emulate here

function fetchheader

Discussion: This function implements the FT_PREFETCHTEXT text option This function uses the helper function "get_header_raw"

function get_header_array

Discussion: This function UN-FOLDS the headers as per RFC2822 "folding, so each element is in fact the intended complete header line, eliminates partial "folded" lines

function get_header_raw

Discussion: This function causes a fetch of the complete, unfiltered RFC2822 format header of the specified message as a text string and returns that text string (i.e. glob)

function fetchbody

Discussion: NOTE: as of Oct 17, 2001, the $part_num used here is not always the same as the part number used for official imap servers. But because this same class produced the fetchstructure, and provided it to the client, and that client will again use this class to get that part, the part number is consistant internally and is MUCH easier to implement in the fetchbody code. However, in the future, the part numbering logic in fetchbody will be coded to exactly match what an official imap server would expect. In the mail_msg class I refer to this "inexact" part number as "mime number dumb" as it is based only on the part's position in the fetchstructure array, before the processing to convert to official imap part number, which mail_msg class refers to as "mime number smart", which is used to access mime parts when using PHP's builtin IMAP module.

function get_body

Discussion: This function implements the IMAP_BODY and also includes a custom boolean param "phpgw_include_header" which also includes unfiltered headers in the return string NEEDED: code for flags: FT_UID; maybe FT_INTERNAL; FT_NOT; flag FT_PEEK has no effect on POP3

file class.mail_filters.inc.php

capability extract multidimentional filter data embedded in this 1 dimentional array

Discussion: php3 limits POST arrays to one level of array key/value pairs thus complex filtering instructions are containded in special strings submitted as controls names action instructions willlook something like this: $filter_X ['action_1_judgement'] => 'fileinto' the "key" string "action_1_judgement" needs to be "decompressed" into an associative array the string means this: a: we are dealing with "action" instructions b: when this data is "decompressed" this would be action[1] data c: that this should be action[1] ["judgement"] where "judgement" is the key, and d: that value of this action[1] ["judgement"] = "fileinto"

file class.mail_msg_base.inc.php

class mail_dcom_holder

Discussion: In tests PHP3 could not handle having an object as a simple array item. Therefor we had to make this class to be the thing that holdes a class.dcom (DataCommunications) object. PHP4 had no problem with the previous code but it was changed to this for backwards compatibility with PHP3, otherwise the script exits with a parse error. Multiple account capability requires that any account can have a stream open to its server at any time, independant of any other DataCommunications object, simce one account may be IMAP while another account may be POP3. Using an array of these mail_dcom_holders, we can achieve this goal and still have PHP3 compatibility.

		$GLOBALS['phpgw_dcom_'.$acctnum] = new mail_dcom_holder;
		$GLOBALS['phpgw_dcom_'.$acctnum]->dcom = CreateObject("email.mail_dcom", $this_server_type);
	now we have an array based structure where each array key can have a DataCommunications object of its 
	own, thereby allowing for multiple mail accounts of any type to be open simultaneously.
		

class mail_msg_base

Discussion: The three files and classes inter relate in the following way to end up with the mail_msg object FIRST, include class mail_msg_base, then SECONDLY incluse mail_msg_wrappers extending mail_msg_base, then THIRDLY include mail_msg which extends mail_msg_wrappers and, by inheritance, mail_msg_base All functions that are at the heart of email functionality are in this class. This class is in the process of being further OOPd so programmers can more easily use it without having to know abou the internal details. When multiple accounts are in use, each active account can be accessed and controlled through this class. Each active account with a stream open to its maiul server has its own DataCommunications object which used to be a part of this class but had to be moved elsewhere for PHP3 compatibility, but still each DataCommunications object is in an array and is accessed via an account number which is comtrolled in this class. This class handles organizing the preferences for each of the multiple accounts. In general, a simple class var array keeps the multiple account information organized as a numbered array based on integer account number. There are already many OOP methods that hide complexities from the programmer, such as the preference and arg access functions. Many of those functions can optionally take an account number and foilder name, but if none is supplies the functions uses logic to obtain valid account number and folder name for whatever account you are dealing with. There is extensice debug output available by setting the various debug flags between 1 to 3, or to 0 if no debug is wanted. More documentation is provided for each function in this class.

classvar known_external_args

Discussion: In a complex app such as email it becomes difficult to keep track of all the GET POST vars that the app is expected to know about. Therefor, all GPC vars this class is expected to be aware of are listed here with an explanation of what they do.

function begin_request

function logout

Discussion: Simplified way to logout. Closes all open streams for all accounts. Usually closing selected streams only is an internal only thing used in special circumstances, so this function SHOULD BE CALLED AT THE END of your page view, for example, just before the last template "pfp" (or whatever output function you use). NOTE: IF THERE IS A WAY TO "HOOK" THIS so it happens AUTOMATICALLY after the last parse of the api template, that would be a "good thing"

function end_request

Discussion: Streams are left open during any particular mail operation and are not closed until this function is called. If this function is not called then the stream becomes a zombie and the mail server will close it after a certain amount of time. Mail streams before PHP 4,2 are not persistent, they last only as long as the page view or mail operation. This function should be called so the streams are properly closed with the logout command to the mail server.

function ensure_stream_and_folder

Discussion: Typically used for moving mail between seperate accounts, use this function to make sure the source or destination mail server stream is open and the required folder is selected. If not, this function will open the connection and select the desired folder.

function login_error

Discussion: ?

function loginerr_tryagain_buggy_cert

Discussion: as of RedHat 7.3 there us a bug in php and UWash requiring unusual mailscr_callstr containing "novalidate-cert" even for NON-SSL connections. If possible, this function adjusts the mailsvr_callstr and continues execution of the script. As long as we "return" from this function, instead of exiting, we can continue the script from where the error occured, assuming we have fixed the error. This is a cool thing, the option to fix and continue just by using "return", or to exit with "phpgw_exit", which ends execution of the script.

function prep_folder_in

Discussion: Mail servers ecpect the foldername to be in a particluar form. This function makes sure of this. If a foldername without a namespace is provided, this function will preform a lookup of all available folders for the given acount and get the closest match. The lookup may be nevessary because the namespace and delimiter can differ from server to server, although most typically the name space is "INBOX" and the delimiter is a period.

function prep_folder_out

Discussion: Folder if not passed will be obtained from the class which keeps track od the folder currently selected, this allows us to call this with no args and the current folder is "prep-ed". Foldnames with spaces and other URL unfriendly chars are encoded here must be decoded on the next input (script session) to undo what we do here.

function ensure_no_brackets

		** note this has chars that will not show up in the inline doc parser **
		ensure_no_brackets('INBOX') = 'INBOX'
		

		** same as syntax but can be viewed in the inline doc parser **
		ensure_no_brackets('{mail.yourserver.com:143}INBOX') results in 'INBOX'
		

function get_mailsvr_callstr

Discussion: After updating to RH73, a new bug popped up where PHP was checking the validity of the mail server certificate even for NON-SSL sessions, under certain circumstances. This has been handles in the login_error routine where this particular error is detected and fixes by adding "novalidate-cert" to the non-ssl imap or pop mailsvr_callstr, note this breaks good servers, so it's handled only after an error pops up and is determined to be a result of this bug. CACHE NOTE: this item is saved in the appsession cache, AND is bese64_encoded there, which encoding and decoding is handled in "save_session_cache_item" and "read_session_cache_item", respectively, where this dataname "mailsvr_namespace" has a special handler for this purpose. because this data has "database unfriendly" chars in it.

		{mail.yourserver.com:143}
		

concept pref_mail_port

Discussion: The preferences for email were designed to *someday* let the user specify a non standard port to use for the mail server. This preference never came to be. The user still can not actually set a port number to use for the mail server. However, in the preferences api there is still code initializing a preference item called "mail_port", with a note that some day it would be user settable, but since it is not currently, the api preferences class has a function to determine the port number based on what kind of server we are connecting to. THIS DOES NOT REALLY BELONG IN PREFS, it never because a user preference, so the api preferences should not be concerned with mail_port. THEREFOR we will SET IT HERE. For backwards compatibility we still set a pref value for mail_port after we are done here, until we replace any code that asks prefs for a port number. Then, port number should be exclusively treated as an "arg" accessable through the OOP style ->get_arg_value('mail_port') function. We do not have a seperate functin for this, we do it here, because the "mail_port" and the "mail_server_type" and the "mailsvr_callstr" are inextricibly linked, they exist only as a related group if data. CONCLUSION: we determine "mail_port" in this function "get_mailsvr_callstr" which is a private function anyway.

function get_mailsvr_namespace

		INBOX    where INBOX is returned as the namespace
		

		get_mailsvr_namespace({mail.servyou.com:143}INBOX) returns INBOX
		

Discussion: for more info see: see http://www.rfc-editor.org/rfc/rfc2342.txt CACHE NOTE: this item is saved in the appsession cache.

function get_mailsvr_delimiter

		(a) typical imap  "INBOX.Sent"  returns the "." as the delimiter, 
		(b) UWash imap (stock mbox)  "email/Sent"  returns the "/" as the delimiter
		

function get_mailsvr_supports_folders

function get_folder_long

Discussion: Note that syntax "NAMESPACE_DELIMITER_FOLDER" is called a "fully qualified" folder name here. The param $feed_folder will be compared to the folder list supplied by the server to insure an accurate folder name is returned because a param $feed_folder LACKING a namespace or delimiter MUST have them added in order to become a "long" folder name, and just guessing is not good enough to ensure accuracy. Works with supported imap servers: UW-Maildir, Cyrus, Courier, UWash Example (Cyrus or Courier): INBOX.Templates Example (if subfolders a.k.a. "inferior folders" are enabled): INBOX.drafts.rfc ???? Example (UW-Maildir only): /home/James.Drafts ???? The above examle would suggext that UW-Maildir takes "~" as namespace and "/" as its pre-folder name delimiter, which as somewhat nonstandard because it appears the rest of the folder name uses "." as the delimiter.

function get_folder_short

Discussion: Simply, this is the folder name without the nor the NAMESPACE nor the DELIMITER preceeding it. Inline docparser repeat: ... without the {serverName:port} nor the NAMESPACE nor the DELIMITER preceeding it. Works with supported imap servers UWash, UW-Maildir, Cyrus, Courier (old) Example (Cyrus or Courier): Templates (old) Example (Cyrus only): drafts.rfc

function get_folder_list

Discussion: returns a numbered array, each element has 2 properties, "folder_long" and "folder_short" so every available folder is in the structure in both long form [namespace][delimiter][foldername] and short form (does not have the [namespace][delimiter] prefix to the folder name) This function can cache data in 2 ways (1) caching as server data in the prefs DB cache department, and (2) in the class var $this->get_arg_value("folder_list") Data will be grabbed from cache when available and when allowed. CACHE NOTE: this item is saved in the appsession cache.

concept UWash IMAP Namespace

Discussion: uwash is file system based, so it requires a filesystem slash after the namespace. Note that with uwash the delimiter is in fact the file system slash. example: requesting list for "mail/*" (NOTE this request will NOT yield a list the INBOX folder included in the returned folder list). However, we have no choice since without the filesystem delimiter, requesting "email*" returns NOTHING. Example queries: (a) "~/" OR (b) if the user specifies specific mbox folder, then: "~/emails/*" OR (c) "emails/*" give the same result, much like a unix "ls" command. At this time we use "unqualified" a.k.a. "relative" directory names if the user provides a namespace. UWash will consider it relative to the mailuser's $HOME property as with "emails/*" (DOES THIS WORK ON ALL PLATFORMS??). BUT we use "~/" if no namespace is given.

concept non-UWash IMAP Server Namespace

Discussion: when handling handle non-UWash IMAP servers, i.e. typical IMAP servers that do not use a filesystem slash as the "delimiter", the last arg is typically "INBOX*" (no dot) which DOES include the inbox in the list of folders. Wheres adding the delimiter "INBOX.*" (has dot) will NOT include the INBOX in the list of folders. So - it's theoretically safe to include the delimiter here, but the INBOX will not be included in the list, this is typically the ONLY TIME you would ever *not* use the delimiter between the namespace and what comes after it. HOWEVER to get *shared* folders included in the return, better NOT include the "." delimiter. For example: Cyrus does not like anything but a "*" as the pattern IF you want shared folders returned. Return data is a list suck as this: INBOX INBOX.Trash (inline docparser repeat): {some.server.com:143}INBOX AND {some.server.com:143}INBOX.Trash

function folder_lookup

Discussion: uses "folder_list[folder_long]" as the "haystack" because it is the most unaltered folder information returned from the server that we have if TRUE, then the "official" folder_long name is returned - the one supplied by the server itself during the get_folder_list routine - "folder_list[folder_long]" if False, an empty string is returned.

function is_imap_folder

Discussion: returns True if the given foldername is probable an IMAP folder. Uses some general criteria such as anything with a DOT_SLASH is probably not the name of an IMAP folder.

function care_about_unseen DEPRECIATED

Discussion: DEPRECIATED function was used when the number of unseen messages in a folder was included in the dropdown folder list combobox HTML select widget.

function encrypt_email_passwd

Discussion: if mcrypt is not enabled, then the password data should be unmolested thru the crypto functions, i.e. do not alter the string if mcrypt will not be preformed on that string.

function decrypt_email_pass

Discussion: if mcrypt is not enabled, then the password data should be unmolested thru the crypto functions, i.e. do not alter the string if mcrypt will not be preformed on that string.

capability Upgrade Routine for 0.9.12 and earlier Custom Passwords DEPRECIATED

Discussion: the phpgw versions prior to and including 0.9.12 *may* have double or even tripple serialized passwd strings stored in their preferences table. SO: (1) check for this (2) unserialize to the real string (3) feed the unserialized / fixed passwd in the prefs class and save the "upgraded" passwd

function make_rfc2822_address

Discussion: will produce a string containing email addresses for (a) display a browser such as on the compose form, or (b) for use in an email mesage header, hence the standards compliance necessity, message headers must follow strict form.

function make_rfc_addy_array

Discussion: To adress(es) in a string as we would get from a submitted compose form hold alot of useful information that can be extracted by sperating out the individual elements of the email address and, if many addresses are present, making an array of this data. This is especially useful during the send procedure, when we feed each individual address to the MTA, because the MTA expects a SIMPLE email address in the RCPT TO: command arg, not an address that contains any of the other things that an email address can contain, such as a users name (personal part) which itself can contain chars outside of the ASCII range (whether ISO encoded or not) that the MTA does not need and does not want to see in the RCPT TO: commands.

		* * using html special chars so the inline doc parser will show the brackets and stuff * *
		->make_rfc_addy_array('john@doe.com,"Php Group"<info@phpgroupware.org>,jerry@example.com,"joe john" <jj@example.com>')
		 which will be decomposed into an array of individual email addresses
		 where each numbered item will be like this this:
		 	array[x]['personal'] 
		 	array[x]['plain'] 
		 the above example would return this structure:
		 	array[0]['personal'] = ""
		 	array[0]['plain'] = "john@doe.com"
		 	array[1]['personal'] = "Php Group"
		 	array[1]['plain'] = "info@phpgroupware.org"
		 	array[2]['personal'] = ""
		 	array[2]['plain'] = "jerry@example.com"
		 	array[3]['personal'] = "joe john"
		 	array[3]['plain'] = "jj@example.com"
		

		ASCII example, inline docs will not show correctly  
		 john
		

		example of verifing a message has been replied to
		if (strisr('Answered'), $flags_str) then (show replied flag)
		

		These are the PHP Sorting definitions and what they do and what their int value is.
	SORTDATE:  0	//This is the Date that the senders email client stanp the message with
	SORTARRIVAL: 1	 //This is the date your email server's MTA stamps the message with
			// using SORTDATE cause some messages to be displayed in the wrong cronologicall order
	SORTFROM:  2
	SORTSUBJECT: 3
	SORTTO:  4  // only used in the "Send" folder
	SORTSIZE:  6
		

		POSSIBLE VALUES FOR [ " m_description " ] ARE 
			container
			packagelist
			presentable/image
			attachment
			presentable
		

		RULES for determining m_description are 
			a) if no subpart(s) then we have either "presentable" or "attachment"
			b) if subpart(s) and a boundary param, then we have a "packagelist" (HeadersOnly)
			c) else we have a container
		

		this is the return structure
		result['is_imap'] boolean - pop3 server do not know what is "new" or not, IMAP servers do
		result['folder_checked'] string - the folder checked, as processed by the msg class, which may have done a lookup on the folder name
		result['alert_string'] string - lang'd string to show the user about status of new messages in this folder
		result['number_new'] integer - for IMAP: the number "recent" and/or "unseen"messages; for POP3: the total number of messages
		result['number_all'] integer - for IMAP and POP3: the total number messages in the folder
		

		HTTP GET URI, example
		< select name="fake_uri_data" > < option value="&item=phone&action=dial&touchtone=1" > ( ... etc ... )
		In an HTTP POST event, this would appear as in the example
		$GLOBALS['HTTP_POST_VARS']['fake_uri_data'] => "&item=phone&action=dial&touchtone=1"
		Then you feed that string into this function and you get back an associave array like this
		return["item"] => "phone"
		return["action"] => "dial"
		return["touchtone"] => "1"
		NOTE: this differs from PHP's parse_str() because this function  will NOT attempt to decode the urlencoded values.
		In this way you may store many data elements in a single HTML "option" value=" " tag.
		

		$GLOBALS["phpgw"]->msg_bootstrap = CreateObject("email.msg_bootstrap");
	$GLOBALS['phpgw']->msg_bootstrap->login();
	## OR, if you care about debug info, an alternative is to use this, does the same thing but gives debug info.
	$GLOBALS['phpgw']->msg_bootstrap->ensure_mail_msg_exists('name of my function');
		

		## email quickstart:
			$GLOBALS["phpgw"]->msg_bootstrap = CreateObject("email.msg_bootstrap");
			$GLOBALS['phpgw']->msg_bootstrap->login();
		

		/index.php?menuaction=email.ui_mail_debug.index