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 |