/* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */

/*
 *  Copyright (C) 2008 OMC Denmark ApS.
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU Affero General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Affero General Public License for more details.
 *
 *  You should have received a copy of the GNU Affero General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef F2T_IMESSAGE_DEF
#define F2T_IMESSAGE_DEF

#pragma prefix "omc.brutus"

#include "types.idl"
#include "IMAPITable.idl"
#include "IMAPIProp.idl"
#include "IAttach.idl"
#include "IMAPIProgress.idl"

module BRUTUS {
        interface IMessage : IMAPIProp {
                BRESULT GetAttachmentTable(in BDEFINE ulFlags,
					   out IMAPITable lppTable);

                BRESULT OpenAttach(in unsigned long ulAttachmentNum,
                                   in GUID lpInterface,
                                   in BDEFINE ulFlags,
                                   out IUnknown lppAttach); // Must be at least IUnknown..

                BRESULT CreateAttach(in GUID lpInterface,
                                     in BDEFINE ulFlags,
                                     out unsigned long lpulAttachmentNum,
                                     out IUnknown lppAttach); // Must be at least IUnknown..

                BRESULT DeleteAttach(in unsigned long ulAttachmentNum,
                                     in IMAPIProgress lpProgress,
                                     in BDEFINE ulFlags);

                BRESULT GetRecipientTable(in BDEFINE ulFlags,
					  out IMAPITable lppTable);

                BRESULT ModifyRecipients(in BDEFINE ulFlags,
					 in ADRLIST lpMods);

		// Fate is the final destination for the server
		// local message after it has been successfully 
		// submitted. 
		//
		// ::SaveChanges() is called internally just before
		// ::SubmitMessage() if (Fate != OUTLOOK_NONE).
		//
		// OUTLOOK_NONE    : Don't do anything. Let the default thing happen.
		// OUTLOOK_DEVNULL : Delete the message after submission.
		// Any other value : Move the message to this specific folder 
		//                   after it has been successfully submitted.
		//
		// MAPI_E_INVALID_PARAMETER will be returned if the Fate
		// folder can not be resolved.
                BRESULT SubmitMessage(in BDEFINE ulFlags,
				      in OUTLOOK_FOLDER Fate); 

                BRESULT SetReadFlag(in BDEFINE ulFlags);

///////////////////////////////////////////////////////////
//                                                       //
// The following functions are generic helper functions. //
// They are *not* a part of IMessage proper.             //
//                                                       //
///////////////////////////////////////////////////////////

		// Will create a custom RFC822 header. The field names
		// and field bodies are 1-1 matching. The strings are used
		// as-is without any codeset or encoding conversions.
		// The field name must be formatted as "FOO" (without apostrophes)
		// where "FOO" is any legal field name. The field body must 
		// be RFC822 compliant.
		BRESULT SetRFC822Headers(in seq_string FieldNames,
					 in seq_string FieldBodies);

		// Hack alert! Needed by e.g ITnef::OpenTaggedBody()
		// A client should *NEVER* have any use for this method!
                BRESULT GetLocalPointer(out unsigned long long Pointer);


		///////////////////////////////////////////////////////////////////////////
		//                                                                       //
		//                       Brutus Recurrence API                           //
		//                                                                       //
		// The start time of the recurring series is often needed as a parameter //
		// here since the time at which any given method is invoked might        //
		// be before SaveChanges() is called. It is therefore not guaranteed     //
		// that the method can retrieve the start time from the native MAPI      //
		// object on its own, thereby necessitating the 'start' in parameter.    //
		//                                                                       //
		// All data manipulation on the native MAPI object is done in an Outlook //
		// 2003 compliant manner.                                                //
		//                                                                       //
		// Reading recurrence state data is therefore only supported if Outlook  //
		// 2003 compliant recurrence information is residing on the native MAPI  //
		// object.                                                               //
		//                                                                       //
		// All Set*() methods in the recurrence API is guaranteed to have        //
		// invoked SaveChanges(KEEP_OPEN_READWRITE) on the native MAPI object    //
		// if, and only if, the return value of the method is BRUTUS_S_OK.       //
		//                                                                       //
		// No Set*() method will have side effects, except for invoking          //
		// SaveChanges to maintain data consistency on the native MAPI object.   //
		// You will therefore need to set at least one or more of:               //
		//                                                                       //
		//     PR_OUTLOOK_EVENT_IS_RECURRING                                     //
		//     PR_OUTLOOK_EVENT_RECURRENCE_TYPE                                  //
		//     PR_OUTLOOK_TASK_IS_RECURRING                                      //
		//                                                                       //
		// aa well as other related properties before invoking any of the Set*() //
		// methods in this recurrence API.                                       //
		//                                                                       //
		///////////////////////////////////////////////////////////////////////////

		// Getting the recurrence state from a non-recurring object 
		// will return a RecurrenceState structure with undefined
		// values, except for the discriminator in the RecurrencePattern
		// union which will have the value of recur_none.
		BRESULT GetRecurrenceState(in boolean is_event,        // to know which property set to use
					   out RecurrenceState state); // general high level information of the state of the recurrence serie

		// This method will get a sequence of all exceptions to the recurrence serie
		BRESULT GetRecurrenceExceptions(in boolean is_event,               // to know which property set to use
						in FILETIME start,                 // start date and time of recurrence sequence
						in OccurrenceTimeType time_format, // requested time format in exception set
						out seq_RecurrenceExceptionData exception_data_set);

		// This will initialize the recurrence pattern. Any recurrence pattern
		// previously available on the object will be overwritten and any 
		// exception information will be lost.
		BRESULT SetRecurrencePattern(in boolean is_event,            // to know which property set to use
					     in FILETIME start,              // start date and time of recurrence sequence
					     in OccurrenceTime end,          // optionally end date and time of series or oID of last occurrence. Ignored for infinite series.
					     in unsigned long duration,      // the duration of unmodified occurrences
					     in DayOfWeek first_day_of_week,
					     in RecurrenceTerminationType how_to_end,
					     in RecurrencePattern pattern);

		// This method will append one exception to a recurring event
		// to whatever exceptions is already present in the series. 
		// If exception data already exist for an occurrence then it
		// will be merged with this incomming data.
		BRESULT SetRecurrenceException(in boolean is_event,       // to know which property set to use
					       in FILETIME start,         // start date and time of recurrence sequence
					       in unsigned long duration, // the duration of unmodified occurrences
					       in seq_RecurrenceExceptionData exception_data_set);

		// This method will delete all exception data for an occurrence
		BRESULT RemoveRecurrenceException(in boolean is_event,        // to know which property set to use
						  in FILETIME start,          // start date and time of recurrence sequence
						  in unsigned long duration,  // the duration of unmodified occurrences
						  in OccurrenceTime oc_time); // the occurrence time for the occurrence in the serie

        };

}; // End of module BRUTUS


#endif
