Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members

scim_socket_transaction.h

Go to the documentation of this file.
00001 /**
00002  * @file scim_socket_transaction.h
00003  * @brief Socket transaction class.
00004  */
00005 
00006 /* 
00007  * Smart Common Input Method
00008  * 
00009  * Copyright (c) 2004 James Su <suzhe@turbolinux.com.cn>
00010  * Copyright (c) 2003 James Su <suzhe@turbolinux.com.cn>
00011  * Copyright (c) 2002 James Su <suzhe@turbolinux.com.cn>
00012  *
00013  *
00014  * This library is free software; you can redistribute it and/or
00015  * modify it under the terms of the GNU Lesser General Public
00016  * License as published by the Free Software Foundation; either
00017  * version 2 of the License, or (at your option) any later version.
00018  *
00019  * This library is distributed in the hope that it will be useful,
00020  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00021  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00022  * GNU Lesser General Public License for more details.
00023  *
00024  * You should have received a copy of the GNU Lesser General Public
00025  * License along with this program; if not, write to the
00026  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
00027  * Boston, MA  02111-1307  USA
00028  *
00029  * $Id: scim_socket_transaction.h,v 1.29 2004/07/05 06:23:58 suzhe Exp $
00030  */
00031 
00032 #ifndef __SCIM_SOCKET_TRANSACTION_H
00033 #define __SCIM_SOCKET_TRANSACTION_H
00034 
00035 namespace scim {
00036 
00037 /**
00038  * @addtogroup SocketCommunication
00039  * @{
00040  */
00041 
00042 /**
00043  * @brief Signature of all valid data types which can be store into transaction.
00044  */
00045 enum SocketTransactionDataType
00046 {
00047     SCIM_TRANS_DATA_UNKNOWN,        //!< Unknown transaction data type.
00048     SCIM_TRANS_DATA_COMMAND,        //!< Send/Receive command.
00049     SCIM_TRANS_DATA_RAW,            //!< Send/Receive raw buffer.
00050     SCIM_TRANS_DATA_UINT32,         //!< Send/Receive uint32.
00051     SCIM_TRANS_DATA_STRING,         //!< Send/Receive String.
00052     SCIM_TRANS_DATA_WSTRING,        //!< Send/Receive WideString.
00053     SCIM_TRANS_DATA_KEYEVENT,       //!< Send/Receive KeyEvent.
00054     SCIM_TRANS_DATA_ATTRIBUTE_LIST, //!< Send/Receive AttributeList.
00055     SCIM_TRANS_DATA_LOOKUP_TABLE,   //!< Send/Receive LookupTable.
00056     SCIM_TRANS_DATA_PROPERTY,       //!< Send/Receive Property.
00057     SCIM_TRANS_DATA_PROPERTY_LIST,  //!< Send/Receive PropertyList.
00058     SCIM_TRANS_DATA_VECTOR_UINT32,  //!< Send/Receive vector<uint32>.
00059     SCIM_TRANS_DATA_VECTOR_STRING,  //!< Send/Receive vector<String>.
00060     SCIM_TRANS_DATA_VECTOR_WSTRING  //!< Send/Receive vector<WideString>.
00061 };
00062 
00063 /**
00064  * @brief Command types used by Socket Frontend/IMEngine/Config and Panel.
00065  * @addtogroup TransactionCommands
00066  * @{
00067  */
00068 const int SCIM_TRANS_CMD_UNKNOWN                          = 0;
00069 
00070 const int SCIM_TRANS_CMD_REQUEST                          = 1;
00071 const int SCIM_TRANS_CMD_REPLY                            = 2;
00072 const int SCIM_TRANS_CMD_OK                               = 3;
00073 const int SCIM_TRANS_CMD_FAIL                             = 4;
00074 
00075 const int SCIM_TRANS_CMD_OPEN_CONNECTION                  = 5;
00076 const int SCIM_TRANS_CMD_CLOSE_CONNECTION                 = 6;
00077 
00078 const int SCIM_TRANS_CMD_LOAD_FILE                        = 7;
00079 const int SCIM_TRANS_CMD_EXIT                             = 99;
00080 
00081 const int SCIM_TRANS_CMD_PROCESS_KEY_EVENT                = 100;
00082 const int SCIM_TRANS_CMD_MOVE_PREEDIT_CARET               = 101;
00083 const int SCIM_TRANS_CMD_SELECT_CANDIDATE                 = 102;
00084 const int SCIM_TRANS_CMD_UPDATE_LOOKUP_TABLE_PAGE_SIZE    = 103;
00085 const int SCIM_TRANS_CMD_LOOKUP_TABLE_PAGE_UP             = 104;
00086 const int SCIM_TRANS_CMD_LOOKUP_TABLE_PAGE_DOWN           = 105;
00087 const int SCIM_TRANS_CMD_RESET                            = 106;
00088 const int SCIM_TRANS_CMD_FOCUS_IN                         = 107;
00089 const int SCIM_TRANS_CMD_FOCUS_OUT                        = 108;
00090 const int SCIM_TRANS_CMD_TRIGGER_PROPERTY                 = 109;
00091 
00092 const int SCIM_TRANS_CMD_SHOW_PREEDIT_STRING              = 110;
00093 const int SCIM_TRANS_CMD_SHOW_AUX_STRING                  = 111;
00094 const int SCIM_TRANS_CMD_SHOW_LOOKUP_TABLE                = 112;
00095 const int SCIM_TRANS_CMD_HIDE_PREEDIT_STRING              = 113;
00096 const int SCIM_TRANS_CMD_HIDE_AUX_STRING                  = 114;
00097 const int SCIM_TRANS_CMD_HIDE_LOOKUP_TABLE                = 115;
00098 const int SCIM_TRANS_CMD_UPDATE_PREEDIT_CARET             = 116;
00099 const int SCIM_TRANS_CMD_UPDATE_PREEDIT_STRING            = 117;
00100 const int SCIM_TRANS_CMD_UPDATE_AUX_STRING                = 118;
00101 const int SCIM_TRANS_CMD_UPDATE_LOOKUP_TABLE              = 119;
00102 const int SCIM_TRANS_CMD_COMMIT_STRING                    = 120;
00103 const int SCIM_TRANS_CMD_FORWARD_KEY_EVENT                = 121;
00104 const int SCIM_TRANS_CMD_REGISTER_PROPERTIES              = 122;
00105 const int SCIM_TRANS_CMD_UPDATE_PROPERTY                  = 123;
00106 
00107 const int SCIM_TRANS_CMD_NEW_INSTANCE                     = 200;
00108 const int SCIM_TRANS_CMD_DELETE_INSTANCE                  = 201;
00109 const int SCIM_TRANS_CMD_DELETE_ALL_INSTANCES             = 202;
00110 
00111 const int SCIM_TRANS_CMD_GET_FACTORY_LIST                 = 203;
00112 const int SCIM_TRANS_CMD_GET_FACTORY_NAME                 = 204;
00113 const int SCIM_TRANS_CMD_GET_FACTORY_AUTHORS              = 205;
00114 const int SCIM_TRANS_CMD_GET_FACTORY_CREDITS              = 206;
00115 const int SCIM_TRANS_CMD_GET_FACTORY_HELP                 = 207;
00116 const int SCIM_TRANS_CMD_GET_FACTORY_LOCALES              = 208;
00117 const int SCIM_TRANS_CMD_GET_FACTORY_ICON_FILE            = 209;
00118 const int SCIM_TRANS_CMD_GET_FACTORY_LANGUAGE             = 210;
00119 
00120 const int SCIM_TRANS_CMD_FLUSH_CONFIG                     = 300;
00121 const int SCIM_TRANS_CMD_ERASE_CONFIG                     = 301;
00122 const int SCIM_TRANS_CMD_GET_CONFIG_STRING                = 302;
00123 const int SCIM_TRANS_CMD_SET_CONFIG_STRING                = 303;
00124 const int SCIM_TRANS_CMD_GET_CONFIG_INT                   = 304;
00125 const int SCIM_TRANS_CMD_SET_CONFIG_INT                   = 305;
00126 const int SCIM_TRANS_CMD_GET_CONFIG_BOOL                  = 306;
00127 const int SCIM_TRANS_CMD_SET_CONFIG_BOOL                  = 307;
00128 const int SCIM_TRANS_CMD_GET_CONFIG_DOUBLE                = 308;
00129 const int SCIM_TRANS_CMD_SET_CONFIG_DOUBLE                = 309;
00130 const int SCIM_TRANS_CMD_GET_CONFIG_VECTOR_STRING         = 310;
00131 const int SCIM_TRANS_CMD_SET_CONFIG_VECTOR_STRING         = 311;
00132 const int SCIM_TRANS_CMD_GET_CONFIG_VECTOR_INT            = 312;
00133 const int SCIM_TRANS_CMD_SET_CONFIG_VECTOR_INT            = 313;
00134 const int SCIM_TRANS_CMD_RELOAD_CONFIG                    = 314;
00135 
00136 const int SCIM_TRANS_CMD_PANEL_COMMAND_START              = 500;
00137 const int SCIM_TRANS_CMD_PANEL_COMMAND_END                = 599;
00138 
00139 const int SCIM_TRANS_CMD_USER_DEFINED                     = 10000;
00140 /**
00141  * @}
00142  */
00143 
00144 
00145 /**
00146  * @brief An exception class to hold SocketTransaction related errors.
00147  *
00148  * scim::SocketTransaction and its related classes must throw
00149  * scim::SocketTransactionError object when error.
00150  */
00151 class SocketTransactionError: public Exception
00152 {
00153 public:
00154     SocketTransactionError (const String& what_arg)
00155         : Exception (String("scim::SocketTransaction: ") + what_arg) { }
00156 };
00157 
00158 /**
00159  * @brief This class is used to pack up many data and commands into one package
00160  *        and send them via socket.
00161  */
00162 class SocketTransaction
00163 {
00164     class SocketTransactionImpl;
00165 
00166     SocketTransactionImpl * m_impl;
00167 
00168     SocketTransaction (const SocketTransaction &);
00169     const SocketTransaction & operator = (const SocketTransaction &);
00170 
00171 public:
00172     /**
00173      * @brief Constructor.
00174      *
00175      * @param bufsize the initial buffer size, maybe grow afterwards.
00176      */
00177     SocketTransaction (size_t bufsize = 512);
00178 
00179     /**
00180      * @brief Destructor.
00181      */
00182     ~SocketTransaction ();
00183 
00184     /**
00185      * @brief Check if the transaction is valid.
00186      *
00187      * @return true if this SocketTransaction object is valid and ready to use.
00188      */
00189     bool valid () const;
00190 
00191     /**
00192      * @brief Write the transaction to a socket.
00193      *
00194      * @param socket the socket to be written to.
00195      * @param signature the leading signature to be written
00196      *        into the socket before the transaction itself,
00197      *        this signature maybe missing when receive the transaction.
00198      *        It's useful to check the connection before receiving
00199      *        a transaction by reading this signature.
00200      *
00201      * @return true if success.
00202      */
00203     bool write_to_socket (const Socket &socket, uint32 signature = 0) const;
00204 
00205     /**
00206      * @brief Read a transaction from a socket.
00207      *
00208      * @param socket the socket to be read from.
00209      * @param timeout time out in millisecond (1/1000 second), -1 means infinity.
00210      *
00211      * @return true if success.
00212      */
00213     bool read_from_socket (const Socket &socket, int timeout = -1);
00214 
00215     /**
00216      * @brief Store a command into this transaction.
00217      *
00218      * @param cmd the command code, like SCIM_TRANS_CMD_FOCUS_IN etc.
00219      */
00220     void put_command (int cmd);
00221 
00222     /**
00223      * @brief Store a uint32 value into this transaction.
00224      */
00225     void put_data (uint32 val);
00226 
00227     /**
00228      * @brief Store a String object into this transaction.
00229      */
00230     void put_data (const String &str);
00231 
00232     /**
00233      * @brief Store a WideString object into this transaction.
00234      */
00235     void put_data (const WideString &str);
00236 
00237     /**
00238      * @brief Store a KeyEvent object into this transaction.
00239      */
00240     void put_data (const KeyEvent &key);
00241 
00242     /**
00243      * @brief Store an AttributeList object into this transaction.
00244      */
00245     void put_data (const AttributeList &attrs);
00246 
00247     /**
00248      * @brief Store a Property object into this transaction.
00249      */
00250     void put_data (const Property &property);
00251 
00252     /**
00253      * @brief Store a PropertyList object into this transaction.
00254      */
00255     void put_data (const PropertyList &properties);
00256 
00257     /**
00258      * @brief Store a LookupTable object into this transaction.
00259      */
00260     void put_data (const LookupTable &table);
00261 
00262     /**
00263      * @brief Store a std::vector<uint32> object into this transaction.
00264      */
00265     void put_data (const std::vector<uint32> &vec);
00266 
00267     /**
00268      * @brief Store a std::vector<String> object into this transaction.
00269      */
00270     void put_data (const std::vector<String> &vec);
00271 
00272     /**
00273      * @brief Store a std::vector<WideString> object into this transaction.
00274      */
00275     void put_data (const std::vector<WideString> &vec);
00276 
00277     /**
00278      * @brief Store a raw buffer into this transaction.
00279      */
00280     void put_data (const char *raw, size_t bufsize);
00281 
00282     /**
00283      * @brief Get the type of the data at current read position.
00284      *
00285      * @return The type of the data can be read currently.
00286      */
00287     SocketTransactionDataType get_data_type () const;
00288 
00289     /**
00290      * @brief Get a command from current read position.
00291      */
00292     bool get_command (int &cmd);
00293 
00294     /**
00295      * @brief Get an uint32 value from current read position.
00296      */
00297     bool get_data (uint32 &val);
00298 
00299     /**
00300      * @brief Get a String from current read position.
00301      */
00302     bool get_data (String &str);
00303 
00304     /**
00305      * @brief Get a WideString from current read position.
00306      */
00307     bool get_data (WideString &str);
00308 
00309     /**
00310      * @brief Get a KeyEvent from current read position.
00311      */
00312     bool get_data (KeyEvent &key);
00313 
00314     /**
00315      * @brief Get an AttributeList from current read position.
00316      */
00317     bool get_data (AttributeList &attrs);
00318 
00319     /**
00320      * @brief Get a Property from current read position.
00321      */
00322     bool get_data (Property &property);
00323 
00324     /**
00325      * @brief Get a PropertyList from current read position.
00326      */
00327     bool get_data (PropertyList &properties);
00328 
00329     /**
00330      * @brief Get a CommonLookupTable from current read position.
00331      */
00332     bool get_data (CommonLookupTable &table);
00333 
00334     /**
00335      * @brief Get a std::vector<uint32> from current read position.
00336      */
00337     bool get_data (std::vector<uint32> &vec);
00338 
00339     /**
00340      * @brief Get a std::vector<String> from current read position.
00341      */
00342     bool get_data (std::vector<String> &vec);
00343 
00344     /**
00345      * @brief Get a std::vector<WideString> from current read position.
00346      */
00347     bool get_data (std::vector<WideString> &vec);
00348 
00349     /**
00350      * @brief Get a raw buffer from current read position.
00351      * 
00352      * if raw == NULL then return the bufsize and skip this data.
00353      * *raw should be deleted afterwards (do not use free!).
00354      */
00355     bool get_data (char **raw, size_t &bufsize);
00356 
00357     /**
00358      * @brief Skip one data from current read position.
00359      */
00360     bool skip_data ();
00361 
00362     /**
00363      * @brief Rewind the current read position, then the data can be read again.
00364      */
00365     void rewind_read_pos ();
00366 
00367     /**
00368      * @brief Clear the transaction, all data in this transaction will be freed.
00369      */
00370     void clear ();
00371 };
00372 
00373 /**
00374  * @brief Helper function to open a connection to a socket server
00375  * with a standard hand shake protocol.
00376  *
00377  * This function is used by a socket client to establish a connection
00378  * between a socket server with a standard hand shake protocol.
00379  *
00380  * The communication between Panel and FrontEnd, SocketFrontEnd and SocketIMEngine,
00381  * SocketFrontEnd and SocketConfig all uses this hand shake protocol.
00382  *
00383  * @param key         A random magic key sent from the socket server
00384  *                    to identify this client in later communications.
00385  * @param client_type The type of this socket client, for example:
00386  *                    "FrontEnd", "GUI", "SocketIMEngine", "SocketConfig" etc.
00387  *                    If the type is "ConnectionTester" then this call just
00388  *                    test if the connection can be established. The client
00389  *                    should close this socket just after the call.
00390  * @param server_type The request socket server type, for example:
00391  *                    "Panel", "SocketFrontEnd" etc.
00392  * @param socket      The reference to the client socket which has been
00393  *                    connected to the socket server.
00394  * @param timeout     The socket read timeout in millisecond, -1 means unlimited.
00395  *
00396  * @return true if the connection was established successfully, otherwise
00397  *         return false, and the client should close the socket.
00398  */
00399 bool   scim_socket_trans_open_connection   (uint32       &key,
00400                                             const String &client_type,
00401                                             const String &server_type,
00402                                             const Socket &socket,
00403                                             int           timeout = -1);
00404 
00405 /**
00406  * @brief Helper function to accept a connection request from a socket client
00407  * with a standard hand shake protocol.
00408  *
00409  * This function is used by a socket server to accept a connection request
00410  * from a socket client which is calling scim_socket_trans_open_connection ().
00411  *
00412  * If a client with type "ConnectionTester" connected to this socket server, then
00413  * this function will return an empty string, but tell the client the connection
00414  * was established successfully.
00415  *
00416  * @param key          A random magic key to identify the socket client in later
00417  *                     communications.
00418  * @param server_types The type of this server, for example:
00419  *                     "SocketFrontEnd", "Panel" etc.
00420  *                     One server can have multiple types, separated by comma.
00421  * @param client_types A list of acceptable client types, separated by comma.
00422  *                     The client type maybe: "FrontEnd", "GUI", "SocketIMEngine" etc.
00423  * @param socket       The socket connected to the client.
00424  * @param timeout      the socket read timeout in millisecond, -1 means unlimited.
00425  *
00426  * @return The type of the accepted socket client, or an empty string if the
00427  *         connection could not be established.
00428  */
00429 String scim_socket_trans_accept_connection (uint32       &key,
00430                                             const String &server_types,
00431                                             const String &client_types,
00432                                             const Socket &socket,
00433                                             int           timeout = -1);
00434 /** @} */
00435 
00436 } // namespace scim
00437 
00438 #endif //__SCIM_SOCKET_TRANSACTION_H
00439 
00440 /*
00441 vi:ts=4:nowrap:ai:expandtab
00442 */
00443 

Generated on Tue Apr 19 00:10:59 2005 for scim by  doxygen 1.4.1