| OLD | NEW |
| 1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. | 1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. |
| 2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
| 3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
| 4 | 4 |
| 5 // Defining IPC Messages | 5 // Defining IPC Messages |
| 6 // | 6 // |
| 7 // Your IPC messages will be defined by macros inside of an XXX_messages.h | 7 // Your IPC messages will be defined by macros inside of an XXX_messages.h |
| 8 // header file. Most of the time, the system can automatically generate all | 8 // header file. Most of the time, the system can automatically generate all |
| 9 // of messaging mechanism from these definitions, but sometimes some manual | 9 // of messaging mechanism from these definitions, but sometimes some manual |
| 10 // coding is required. In these cases, you will also have an XXX_messages.cc | 10 // coding is required. In these cases, you will also have an XXX_messages.cc |
| 11 // implemation file as well. | 11 // implementation file as well. |
| 12 // | 12 // |
| 13 // The senders of your messages will include your XXX_messages.h file to | 13 // The senders of your messages will include your XXX_messages.h file to |
| 14 // get the full set of definitions they need to send your messages. | 14 // get the full set of definitions they need to send your messages. |
| 15 // | 15 // |
| 16 // Each XXX_messages.h file must be registered with the IPC system. This | 16 // Each XXX_messages.h file must be registered with the IPC system. This |
| 17 // requires adding two things: | 17 // requires adding two things: |
| 18 // - An XXXMsgStart value to the IPCMessageStart enum in ipc_message_start.h | 18 // - An XXXMsgStart value to the IPCMessageStart enum in ipc_message_start.h |
| 19 // - An inclusion of XXX_messages.h file in a message generator .h file | 19 // - An inclusion of XXX_messages.h file in a message generator .h file |
| 20 // | 20 // |
| 21 // The XXXMsgStart value is an enumeration that ensures uniqueness for | 21 // The XXXMsgStart value is an enumeration that ensures uniqueness for |
| 22 // each different message file. Later, you will use this inside your | 22 // each different message file. Later, you will use this inside your |
| 23 // XXX_messages.h file before invoking message declaration macros: | 23 // XXX_messages.h file before invoking message declaration macros: |
| 24 // #define IPC_MESSAGE_START XXXMsgStart | 24 // #define IPC_MESSAGE_START XXXMsgStart |
| 25 // ( ... your macro invocations go here ... ) | 25 // ( ... your macro invocations go here ... ) |
| 26 // | 26 // |
| 27 // Message Generator Files | 27 // Message Generator Files |
| 28 // | 28 // |
| 29 // A message generator .h header file pulls in all other message-declaring | 29 // A message generator .h header file pulls in all other message-declaring |
| 30 // headers for a given component. It is included by a message generator | 30 // headers for a given component. It is included by a message generator |
| 31 // .cc file, which is where all the generated code will wind up. Typically, | 31 // .cc file, which is where all the generated code will wind up. Typically, |
| 32 // you will use an existing generator (e.g. common_message_generator.cc | 32 // you will use an existing generator (e.g. common_message_generator.cc |
| 33 // in /chrome/common), but there are circumstances where you may add a | 33 // in /chrome/common), but there are circumstances where you may add a |
| 34 // new one. | 34 // new one. |
| 35 // | 35 // |
| 36 // In the rare cicrucmstances where you can't re-use an existing file, | 36 // In the rare circumstances where you can't re-use an existing file, |
| 37 // your YYY_message_generator.cc file for a component YYY would contain | 37 // your YYY_message_generator.cc file for a component YYY would contain |
| 38 // the following code: | 38 // the following code: |
| 39 // // Get basic type definitions. | 39 // // Get basic type definitions. |
| 40 // #define IPC_MESSAGE_IMPL | 40 // #define IPC_MESSAGE_IMPL |
| 41 // #include "path/to/YYY_message_generator.h" | 41 // #include "path/to/YYY_message_generator.h" |
| 42 // // Generate constructors. | 42 // // Generate constructors. |
| 43 // #include "ipc/struct_constructor_macros.h" | 43 // #include "ipc/struct_constructor_macros.h" |
| 44 // #include "path/to/YYY_message_generator.h" | 44 // #include "path/to/YYY_message_generator.h" |
| 45 // // Generate destructors. | 45 // // Generate destructors. |
| 46 // #include "ipc/struct_destructor_macros.h" | 46 // #include "ipc/struct_destructor_macros.h" |
| (...skipping 18 matching lines...) Expand all Loading... |
| 65 // file, put the following after all the includes for param types: | 65 // file, put the following after all the includes for param types: |
| 66 // #define IPC_MESSAGE_IMPL | 66 // #define IPC_MESSAGE_IMPL |
| 67 // #include "XXX_messages.h" | 67 // #include "XXX_messages.h" |
| 68 // (... implementation of traits not auto-generated ...) | 68 // (... implementation of traits not auto-generated ...) |
| 69 // | 69 // |
| 70 // Multiple Inclusion | 70 // Multiple Inclusion |
| 71 // | 71 // |
| 72 // The XXX_messages.h file will be multiply-included by the | 72 // The XXX_messages.h file will be multiply-included by the |
| 73 // YYY_message_generator.cc file, so your XXX_messages file can't be | 73 // YYY_message_generator.cc file, so your XXX_messages file can't be |
| 74 // guarded in the usual manner. Ideally, there will be no need for any | 74 // guarded in the usual manner. Ideally, there will be no need for any |
| 75 // inclusion guard, since the XXX_messages.h file should consist soley | 75 // inclusion guard, since the XXX_messages.h file should consist solely |
| 76 // of inclusions of other headers (which are self-guarding) and IPC | 76 // of inclusions of other headers (which are self-guarding) and IPC |
| 77 // macros (which are multiply evaluating). | 77 // macros (which are multiply evaluating). |
| 78 // | 78 // |
| 79 // Note that #pragma once cannot be used here; doing so would mark the whole | 79 // Note that #pragma once cannot be used here; doing so would mark the whole |
| 80 // file as being singly-included. Since your XXX_messages.h file is only | 80 // file as being singly-included. Since your XXX_messages.h file is only |
| 81 // partially-guarded, care must be taken to ensure that it is only included | 81 // partially-guarded, care must be taken to ensure that it is only included |
| 82 // by other .cc files (and the YYY_message_generator.h file). Including an | 82 // by other .cc files (and the YYY_message_generator.h file). Including an |
| 83 // XXX_messages.h file in some other .h file may result in duplicate | 83 // XXX_messages.h file in some other .h file may result in duplicate |
| 84 // declarations and a compilation failure. | 84 // declarations and a compilation failure. |
| 85 // | 85 // |
| 86 // Type Declarations | 86 // Type Declarations |
| 87 // | 87 // |
| 88 // It is generally a bad idea to have type definitions in a XXX_messages.h | 88 // It is generally a bad idea to have type definitions in a XXX_messages.h |
| 89 // file; most likely the typedef will then be used in the message, as opposed | 89 // file; most likely the typedef will then be used in the message, as opposed |
| 90 // to the struct iself. Later, an IPC message dispatcher wil need to call | 90 // to the struct itself. Later, an IPC message dispatcher will need to call |
| 91 // a function taking that type, and that function is declared in some other | 91 // a function taking that type, and that function is declared in some other |
| 92 // header. Thus, in order to get the type definition, the other header | 92 // header. Thus, in order to get the type definition, the other header |
| 93 // would have to include the XXX_messages.h file, violating the rule above | 93 // would have to include the XXX_messages.h file, violating the rule above |
| 94 // about not including XXX_messages.h file in other .h files. | 94 // about not including XXX_messages.h file in other .h files. |
| 95 // | 95 // |
| 96 // One approach here is to move these type definitions to another (guarded) | 96 // One approach here is to move these type definitions to another (guarded) |
| 97 // .h file and include this second .h in your XXX_messages.h file. This | 97 // .h file and include this second .h in your XXX_messages.h file. This |
| 98 // is still less than ideal, because the dispatched function would have to | 98 // is still less than ideal, because the dispatched function would have to |
| 99 // redeclare the typedef or include this second header. This may be | 99 // redeclare the typedef or include this second header. This may be |
| 100 // reasonable in a few cases. | 100 // reasonable in a few cases. |
| 101 // | 101 // |
| 102 // Failing all of the above, then you will want to bracket the smallest | 102 // Failing all of the above, then you will want to bracket the smallest |
| 103 // possible section of your XXX_messages.h file containing these types | 103 // possible section of your XXX_messages.h file containing these types |
| 104 // with an include guard macro. Be aware that providing an incomplete | 104 // with an include guard macro. Be aware that providing an incomplete |
| 105 // class type declaration to avoid pulling in a long chain of headers is | 105 // class type declaration to avoid pulling in a long chain of headers is |
| 106 // acceptable when your XXX_messages.h header is being included by the | 106 // acceptable when your XXX_messages.h header is being included by the |
| 107 // message sending caller's code, but not when the YYY_message_generator.c | 107 // message sending caller's code, but not when the YYY_message_generator.c |
| 108 // is building the messages. In addtion, due to the multiple inclusion | 108 // is building the messages. In addition, due to the multiple inclusion |
| 109 // restriction, these type ought to be guarded. Follow a convention like: | 109 // restriction, these type ought to be guarded. Follow a convention like: |
| 110 // #ifndef SOME_GUARD_MACRO | 110 // #ifndef SOME_GUARD_MACRO |
| 111 // #define SOME_GUARD_MACRO | 111 // #define SOME_GUARD_MACRO |
| 112 // class some_class; // One incomplete class declaration | 112 // class some_class; // One incomplete class declaration |
| 113 // class_some_other_class; // Another incomplete class declaration | 113 // class_some_other_class; // Another incomplete class declaration |
| 114 // #endif // SOME_GUARD_MACRO | 114 // #endif // SOME_GUARD_MACRO |
| 115 // #ifdef IPC_MESSAGE_IMPL | 115 // #ifdef IPC_MESSAGE_IMPL |
| 116 // #include "path/to/some_class.h" // Full class declaration | 116 // #include "path/to/some_class.h" // Full class declaration |
| 117 // #include "path/to/some_other_class.h" // Full class declaration | 117 // #include "path/to/some_other_class.h" // Full class declaration |
| 118 // #endif // IPC_MESSAGE_IMPL | 118 // #endif // IPC_MESSAGE_IMPL |
| 119 // (.. IPC macros using some_class and some_other_class ...) | 119 // (.. IPC macros using some_class and some_other_class ...) |
| 120 // | 120 // |
| 121 // Macro Invocations | 121 // Macro Invocations |
| 122 // | 122 // |
| 123 // You will use IPC message macro invocations for three things: | 123 // You will use IPC message macro invocations for three things: |
| 124 // - New struct definitions for IPC | 124 // - New struct definitions for IPC |
| 125 // - Registering existing struct and enum definitions with IPC | 125 // - Registering existing struct and enum definitions with IPC |
| 126 // - Defining the messages themselves | 126 // - Defining the messages themselves |
| 127 // | 127 // |
| 128 // New structs are defined with IPC_STRUCT_BEGIN(), IPC_STRUCT_MEMBER(), | 128 // New structs are defined with IPC_STRUCT_BEGIN(), IPC_STRUCT_MEMBER(), |
| 129 // IPC_STRUCT_END() family of macros. These cause the XXX_messages.h | 129 // IPC_STRUCT_END() family of macros. These cause the XXX_messages.h |
| 130 // to proclaim equivalent struct declarations for use by callers, as well | 130 // to proclaim equivalent struct declarations for use by callers, as well |
| 131 // as later registering the type with the message generation. Note that | 131 // as later registering the type with the message generation. Note that |
| 132 // IPC_STRUCT_MEMBER() is only permitted inside matching calls to | 132 // IPC_STRUCT_MEMBER() is only permitted inside matching calls to |
| 133 // IPC_STRUCT_BEGIN() / IPC_STRUCT_END(). There is also an | 133 // IPC_STRUCT_BEGIN() / IPC_STRUCT_END(). There is also an |
| 134 // IPC_STRUCT_BEGIN_WITH_PARENT(), which behaves like IPC_STRUCT_BEGIN(), | 134 // IPC_STRUCT_BEGIN_WITH_PARENT(), which behaves like IPC_STRUCT_BEGIN(), |
| 135 // but also accomodates structs that inherit from other structs. | 135 // but also accommodates structs that inherit from other structs. |
| 136 // | 136 // |
| 137 // Externally-defined structs are registered with IPC_STRUCT_TRAITS_BEGIN(), | 137 // Externally-defined structs are registered with IPC_STRUCT_TRAITS_BEGIN(), |
| 138 // IPC_STRUCT_TRAITS_MEMBER(), and IPC_STRUCT_TRAITS_END() macros. These | 138 // IPC_STRUCT_TRAITS_MEMBER(), and IPC_STRUCT_TRAITS_END() macros. These |
| 139 // cause registration of the types with message generation only. | 139 // cause registration of the types with message generation only. |
| 140 // There's also IPC_STRUCT_TRAITS_PARENT, which is used to register a parent | 140 // There's also IPC_STRUCT_TRAITS_PARENT, which is used to register a parent |
| 141 // class (whose own traits are already defined). Note that | 141 // class (whose own traits are already defined). Note that |
| 142 // IPC_STRUCT_TRAITS_MEMBER() and IPC_STRUCT_TRAITS_PARENT are only permitted | 142 // IPC_STRUCT_TRAITS_MEMBER() and IPC_STRUCT_TRAITS_PARENT are only permitted |
| 143 // inside matching calls to IPC_STRUCT_TRAITS_BEGIN() / | 143 // inside matching calls to IPC_STRUCT_TRAITS_BEGIN() / |
| 144 // IPC_STRUCT_TRAITS_END(). | 144 // IPC_STRUCT_TRAITS_END(). |
| 145 // | 145 // |
| (...skipping 827 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 973 // This corresponds to an enum value from IPCMessageStart. | 973 // This corresponds to an enum value from IPCMessageStart. |
| 974 #define IPC_MESSAGE_CLASS(message) \ | 974 #define IPC_MESSAGE_CLASS(message) \ |
| 975 IPC_MESSAGE_ID_CLASS(message.type()) | 975 IPC_MESSAGE_ID_CLASS(message.type()) |
| 976 | 976 |
| 977 #endif // IPC_IPC_MESSAGE_MACROS_H_ | 977 #endif // IPC_IPC_MESSAGE_MACROS_H_ |
| 978 | 978 |
| 979 // Clean up IPC_MESSAGE_START in this unguarded section so that the | 979 // Clean up IPC_MESSAGE_START in this unguarded section so that the |
| 980 // XXX_messages.h files need not do so themselves. This makes the | 980 // XXX_messages.h files need not do so themselves. This makes the |
| 981 // XXX_messages.h files easier to write. | 981 // XXX_messages.h files easier to write. |
| 982 #undef IPC_MESSAGE_START | 982 #undef IPC_MESSAGE_START |
| OLD | NEW |