ipcITransactionService.idl

/* ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is Mozilla Transaction Manager. * * The Initial Developer of the Original Code is * Netscape Communications Corp. * Portions created by the Initial Developer are Copyright (C) 2003 * the Initial Developer. All Rights Reserved. * * Contributor(s): * John Gaunt <jgaunt@netscape.com> * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */// from tmTransactionManager.h//// XXX documentation needs work//////////////////////////////////////////////////////////////////////////////// Overview of TransactionManager IPC Module//// Classes:// tmIPCModule - From the tmTransactionManager's point of view, this// is a proxy for the IPC daemon itself. The reverse is true// from the daemon's point of view. This is an interface for the// Transaction system to work with the IPC daemon as its transport// layer.// tmTransactionManager (TM) - Manages the different queues. Maintains// the queues neccessary for different clients. Receives messages// from the tmIPCModule and passes message to the IPC daemon through// the tmIPCModule.// tmQueue - this class manages the transactions for the different areas// of the profiles being shared. Broken down by functional area there// will be a queue for prefs, cookies etc, but not for profileA and // profileB, and not for pref_delete, pref_create, pref_change etc...// tmTransaction - the actual transaction being shared with the different// tmClients. It contains the type of transaction, which will equate with// a type of queue in existance, the owner of the transaction (an IPC daemon ID)// and the actual text message to be shared. /////////////////////////////////////////////////////////////////////////////////// XXX some docs that need to be put somewhere://// from tmqueue.cpp// Docs - note that the status of the TM_ATTACH_REPLY is only for checking// for TM_ERROR_FAILURE. Other numbers have no importance// success of the status means the NS_ERROR_GET_CODE(status) will // yield the index of the listener.//// move to documentation page - from tmqueue.h//// a queue is specific to profile//// UUID going out from the module is a handler in the client // (will go to the XPCOM service impling that UUID)// -- does it make sense to have different UUIDs for cookies/prefs/etc//#include "nsISupports.idl"
interface ipcITransactionObserver;
[scriptable, uuid(15561efb-8c58-4a47-813a-fa91cf730895)]
interface ipcITransactionService : nsISupports
{ /** * Connects the application to the transaction manager, defines the * namespace and initializes internal storage * * @param aNamespace * A string defining the scope of the transaction domains. It is * used internally to seperate process listening to the same domain * (ie. preferences) but for two different namespaces (ie. profile1 vs * profile2). * * @returns NS_OK if all memory allocated properly and the IPC service was * reached and attached to successfully. * * @returns an NS_ERROR_<foo> code specific to the failure otherwise */voidinit(in ACString aNamespace);
/** * Links the observer passed in with the domain specified. This will allow * the observer to post transactions dealing with this domain as well as * receive transactions posted by other applications observing this * domain. * * Return codes for this method confer information about the success of * this call, not of the actual attaching of the observer to the domain. * (except the TM_ERROR code - which means the observer can not attach) * If the attach is successful the observer will have its OnAttachReply * method called before this method returns. * * Note: This call is synchronous and will not return until the call to * OnAttachReply is made. * * @param aDomainName * the name of the domain, in the current namespace, to listen for * transactions from. i.e. cookies * * @param aObserver * this will be used to notify the application when transactions * and messages come in. * * @param aLockingCall * Have the Transaction Sevice acquire a lock based on the domain * before attaching. This should be used when persistant storage * is being used to prevent data corruption. * * @returns NS_OK if the attach message was sent to the Transaction Manager. * * @returns an NS_ERROR_<foo> code specific to the failure otherwise * * @returns TM_ERROR_QUEUE_EXISTS if the queue already exists which means * someone has already attached to it. */void attach(in ACString aDomainName,
in ipcITransactionObserver aObserver,
in PRBool aLockingCall);
/** * Sends a detach message to the Transaction Manager to unlink the observer * associated with the domain passed in. * * As in attach, return codes do not indicate success of detachment. The * observer will have it's OnDetach method called if it is successfully * detached. * * Note: This call is an asynchronous call. * * @param aDomainName * the domain, in the current namespace, from which the client * should be removed. * * @returns NS_OK if the detach message is sent to the Transaction Manager * * @returns NS_ERROR_FAILURE is something goes wrong * * @returns NS_ERRROR_UNEXPECTD if the domain does not have an observer * attached */void detach(in ACString aDomainName);
/** * Sends a flush message to the Transaction Manager to remove all * transactions for the domain. After this call there will be no * transactions in the Transaction Manager for the namespace/domain * pairing. It is up to the application to coordinate the flushing * of the Transaction Manager with the writing of data to files, * if needed. * * Note: This call is synchronous and will not return until the call to * OnFlushReply is made. * * @param aDomainName * The domain, in the current namespace, to flush. * * @param aLockingCall * Have the Transaction Sevice acquire a lock based on the domain * before flushing. This should be used when persistant storage * is being used to prevent data corruption. * * @returns NS_OK if the flush message is sent to the Transaction Manager * * @returns NS_ERROR_FAILURE is something goes wrong * * @returns NS_ERRROR_UNEXPECTD if the domain does not have an observer * attached */void flush(in ACString aDomainName, in PRBool aLockingCall);
/** * Send the data to the Transaction Manager to be broadcast to any * applications that have registered as observers of this particular * namespace/domain pairing. * * If this domain is not being observed (attach has not been called for * this domain) the message is queued until the attach is made and then * the message is sent to the Transaction Manager with the proper domain * information. * * XXXjg - this may not be neccessary with the synch attach call. * * Note: This call is an asynchronous call. * * @param aDomainName * the domain, in the current namespace, to which the data will be * sent. * * @param aData * The actual data to be sent. * * @param aDataLen * The length of the data argument */void postTransaction(in ACString aDomainName,
[array, const, size_is(aDataLen)]
in octet aData,
in unsignedlong aDataLen);
};
%{C++
// singleton implementing ipcITransactionService#define IPC_TRANSACTIONSERVICE_CLASSNAME \ "tmTransactionService"#define IPC_TRANSACTIONSERVICE_CONTRACTID \ "@mozilla.org/ipc/transaction-service;1"#define IPC_TRANSACTIONSERVICE_CID \{ /* 1403adf4-94d1-4c67-a8ae-d9f86972d378 */ \
0x1403adf4, \
0x94d1, \
0x4c67, \
{0xa8, 0xae, 0xd9, 0xf8, 0x69, 0x72, 0xd3, 0x78} \
}
%}