X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/cdbcf4c286ea989bfb8922a54d9e3f80b3fc9bcb..7ace5fd8e03c5b49d672e0363a8d4960bbf80592:/interface/dde.h diff --git a/interface/dde.h b/interface/dde.h index a82303d763..66b979df74 100644 --- a/interface/dde.h +++ b/interface/dde.h @@ -11,54 +11,64 @@ @wxheader{dde.h} A wxDDEConnection object represents the connection between a client and a - server. It can be created by making a connection using a - wxDDEClient object, or by the acceptance of a connection by a - wxDDEServer object. The bulk of a DDE (Dynamic Data Exchange) - conversation is controlled by - calling members in a @b wxDDEConnection object or by overriding its - members. + server. It can be created by making a connection using a wxDDEClient + object, or by the acceptance of a connection by a wxDDEServer object. The + bulk of a DDE (Dynamic Data Exchange) conversation is controlled by calling + members in a wxDDEConnection object or by overriding its members. An application should normally derive a new connection class from - wxDDEConnection, in order to override the communication event handlers - to do something interesting. + wxDDEConnection, in order to override the communication event handlers to + do something interesting. - This DDE-based implementation is available on Windows only, - but a platform-independent, socket-based version - of this API is available using wxTCPConnection. + This DDE-based implementation is available on Windows only, but a + platform-independent, socket-based version of this API is available using + wxTCPConnection. @library{wxbase} - @category{FIXME} + @category{ipc} - @see wxDDEClient, wxDDEServer, @ref overview_ipcoverview "Interprocess - communications overview" + @see wxConnectionBase, wxDDEClient, wxDDEServer, @ref overview_ipc */ -class wxDDEConnection : public wxObject +class wxDDEConnection : public wxConnectionBase { public: - //@{ /** Constructs a connection object. If no user-defined connection object is to be derived from wxDDEConnection, then the constructor should not be - called directly, since the default connection object will be provided on - requesting (or accepting) a connection. However, if the user defines his - or her own derived connection object, the wxDDEServer::OnAcceptConnection - and/or wxDDEClient::OnMakeConnection members should be replaced by - functions which construct the new connection object. If the arguments of - the wxDDEConnection constructor are void, then a default buffer is - associated with the connection. Otherwise, the programmer must provide a - a buffer and size of the buffer for the connection object to use in - transactions. + called directly, since the default connection object will be provided + on requesting (or accepting) a connection. However, if the user defines + his or her own derived connection object, the + wxDDEServer::OnAcceptConnection() and/or + wxDDEClient::OnMakeConnection() members should be replaced by functions + which construct the new connection object. + + A default buffer will be associated with this connection. */ wxDDEConnection(); + /** + Constructs a connection object. If no user-defined connection object is + to be derived from wxDDEConnection, then the constructor should not be + called directly, since the default connection object will be provided + on requesting (or accepting) a connection. However, if the user defines + his or her own derived connection object, the + wxDDEServer::OnAcceptConnection() and/or + wxDDEClient::OnMakeConnection() members should be replaced by functions + which construct the new connection object. + + @param buffer + Buffer for this connection object to use in transactions. + @param size + Size of the buffer given. + */ wxDDEConnection(void* buffer, size_t size); - //@} //@{ /** Called by the server application to advise the client of a change in - the data associated with the given item. Causes the client - connection's OnAdvise() - member to be called. Returns @true if successful. + the data associated with the given item. Causes the client connection's + OnAdvise() member to be called. + + @return @true if successful. */ bool Advise(const wxString& item, const void* data, size_t size, wxIPCFormat format = wxIPC_PRIVATE); @@ -69,22 +79,24 @@ public: /** Called by the client or server application to disconnect from the other - program; it causes the OnDisconnect() message - to be sent to the corresponding connection object in the other - program. The default behaviour of @b OnDisconnect is to delete the - connection, but the calling application must explicitly delete its - side of the connection having called @b Disconnect. Returns @true if - successful. + program; it causes the OnDisconnect() message to be sent to the + corresponding connection object in the other program. The default + behaviour of OnDisconnect() is to delete the connection, but the + calling application must explicitly delete its side of the connection + having called Disconnect(). + + @return @true if successful. */ bool Disconnect(); //@{ /** - Called by the client application to execute a command on the server. Can - also be used to transfer arbitrary data to the server (similar - to Poke() in that respect). Causes the - server connection's OnExecute() member to be - called. Returns @true if successful. + Called by the client application to execute a command on the server. + Can also be used to transfer arbitrary data to the server (similar to + Poke() in that respect). Causes the server connection's OnExecute() + member to be called. + + @return @true if successful. */ bool Execute(const void* data, size_t size, wxIPCFormat format = wxIPC_PRIVATE); @@ -97,11 +109,8 @@ public: Message sent to the client application when the server notifies it of a change in the data associated with the given item. */ - virtual bool OnAdvise(const wxString& topic, - const wxString& item, - const void* data, - size_t size, - wxIPCFormat format); + virtual bool OnAdvise(const wxString& topic, const wxString& item, + const void* data, size_t size, wxIPCFormat format); /** Message sent to the client or server application when the other @@ -116,52 +125,46 @@ public: this message. */ virtual bool OnExecute(const wxString& topic, const void* data, - size_t size, - wxIPCFormat format); + size_t size, wxIPCFormat format); /** Message sent to the server application when the client notifies it to accept the given data. */ virtual bool OnPoke(const wxString& topic, const wxString& item, - const void* data, - size_t size, - wxIPCFormat format); + const void* data, size_t size, wxIPCFormat format); /** - Message sent to the server application when the client - calls Request(). The server - should respond by returning a character string from @b OnRequest, - or @NULL to indicate no data. + Message sent to the server application when the client calls Request(). + The server should respond by returning a character string from + OnRequest(), or @NULL to indicate no data. */ virtual const void* OnRequest(const wxString& topic, - const wxString& item, - size_t* size, + const wxString& item, size_t* size, wxIPCFormat format); /** Message sent to the server application by the client, when the client - wishes to start an 'advise loop' for the given topic and item. The + wishes to start an "advise loop" for the given topic and item. The server can refuse to participate by returning @false. */ - virtual bool OnStartAdvise(const wxString& topic, - const wxString& item); + virtual bool OnStartAdvise(const wxString& topic, const wxString& item); /** Message sent to the server application by the client, when the client - wishes to stop an 'advise loop' for the given topic and item. The + wishes to stop an "advise loop" for the given topic and item. The server can refuse to stop the advise loop by returning @false, although this doesn't have much meaning in practice. */ - virtual bool OnStopAdvise(const wxString& topic, - const wxString& item); + virtual bool OnStopAdvise(const wxString& topic, const wxString& item); //@{ /** Called by the client application to poke data into the server. Can be used to transfer arbitrary data to the server. Causes the server - connection's OnPoke() member - to be called. Returns @true if successful. + connection's OnPoke() member to be called. + + @return @true if successful. */ bool Poke(const wxString& item, const void* data, size_t size, wxIPCFormat format = wxIPC_PRIVATE); @@ -171,26 +174,30 @@ public: //@} /** - Called by the client application to request data from the server. Causes - the server connection's OnRequest() member to be called. Returns a - character string (actually a pointer to the connection's buffer) if - successful, @NULL otherwise. + Called by the client application to request data from the server. + Causes the server connection's OnRequest() member to be called. + + @return A character string (actually a pointer to the connection's + buffer) if successful, @NULL otherwise. */ const void* Request(const wxString& item, size_t* size, wxIPCFormat format = wxIPC_TEXT); /** - Called by the client application to ask if an advise loop can be started - with the server. Causes the server connection's OnStartAdvise() - member to be called. Returns @true if the server okays it, @false - otherwise. + Called by the client application to ask if an advise loop can be + started with the server. Causes the server connection's OnStartAdvise() + member to be called. + + @return @true if the server okays it, @false otherwise. */ bool StartAdvise(const wxString& item); /** Called by the client application to ask if an advise loop can be - stopped. Causes the server connection's OnStopAdvise() member - to be called. Returns @true if the server okays it, @false otherwise. + stopped. Causes the server connection's OnStopAdvise() member to be + called. + + @return @true if the server okays it, @false otherwise. */ bool StopAdvise(const wxString& item); }; @@ -204,22 +211,21 @@ public: A wxDDEClient object represents the client part of a client-server DDE (Dynamic Data Exchange) conversation. - To create a client which can communicate with a suitable server, - you need to derive a class from wxDDEConnection and another from wxDDEClient. - The custom wxDDEConnection class will intercept communications in - a 'conversation' with a server, and the custom wxDDEServer is required - so that a user-overridden wxDDEClient::OnMakeConnection member can return - a wxDDEConnection of the required class, when a connection is made. + To create a client which can communicate with a suitable server, you need + to derive a class from wxDDEConnection and another from wxDDEClient. The + custom wxDDEConnection class will intercept communications in a + "conversation" with a server, and the custom wxDDEServer is required so + that a user-overridden OnMakeConnection() member can return a + wxDDEConnection of the required class, when a connection is made. - This DDE-based implementation is - available on Windows only, but a platform-independent, socket-based version - of this API is available using wxTCPClient. + This DDE-based implementation is available on Windows only, but a + platform-independent, socket-based version of this API is available using + wxTCPClient. @library{wxbase} - @category{FIXME} + @category{ipc} - @see wxDDEServer, wxDDEConnection, @ref overview_ipcoverview "Interprocess - communications overview" + @see wxDDEServer, wxDDEConnection, @ref overview_ipc */ class wxDDEClient : public wxObject { @@ -230,13 +236,13 @@ public: wxDDEClient(); /** - Tries to make a connection with a server specified by the host - (machine name under UNIX, ignored under Windows), service name (must - contain an integer port number under UNIX), and topic string. If the - server allows a connection, a wxDDEConnection object will be returned. - The type of wxDDEConnection returned can be altered by overriding - the OnMakeConnection() member to return your own - derived connection object. + Tries to make a connection with a server specified by the host (machine + name under UNIX, ignored under Windows), service name (must contain an + integer port number under UNIX), and topic string. If the server allows + a connection, a wxDDEConnection object will be returned. + + The type of wxDDEConnection returned can be altered by overriding the + OnMakeConnection() member to return your own derived connection object. */ wxConnectionBase* MakeConnection(const wxString& host, const wxString& service, @@ -244,19 +250,20 @@ public: /** The type of wxDDEConnection returned from a MakeConnection() call can - be altered by deriving the @b OnMakeConnection member to return your - own derived connection object. By default, a wxDDEConnection - object is returned. + be altered by deriving the OnMakeConnection() member to return your own + derived connection object. By default, a wxDDEConnection object is + returned. + The advantage of deriving your own connection class is that it will - enable you to intercept messages initiated by the server, such - as wxDDEConnection::OnAdvise. You may also want to - store application-specific data in instances of the new class. + enable you to intercept messages initiated by the server, such as + wxDDEConnection::OnAdvise(). You may also want to store + application-specific data in instances of the new class. */ wxConnectionBase* OnMakeConnection(); /** - Returns @true if this is a valid host name, @false otherwise. This always - returns @true under MS Windows. + Returns @true if this is a valid host name, @false otherwise. This + always returns @true under MS Windows. */ bool ValidHost(const wxString& host); }; @@ -270,14 +277,14 @@ public: A wxDDEServer object represents the server part of a client-server DDE (Dynamic Data Exchange) conversation. - This DDE-based implementation is - available on Windows only, but a platform-independent, socket-based version - of this API is available using wxTCPServer. + This DDE-based implementation is available on Windows only, but a + platform-independent, socket-based version of this API is available using + wxTCPServer. @library{wxbase} - @category{FIXME} + @category{ipc} - @see wxDDEClient, wxDDEConnection, @ref overview_ipcoverview "IPC overview" + @see wxDDEClient, wxDDEConnection, @ref overview_ipc */ class wxDDEServer { @@ -290,20 +297,22 @@ public: /** Registers the server using the given service name. Under UNIX, the string must contain an integer id which is used as an Internet port - number. @false is returned if the call failed (for example, the port + number. @false is returned if the call failed (for example, if the port number is already in use). */ bool Create(const wxString& service); /** - When a client calls @b MakeConnection, the server receives the - message and this member is called. The application should derive a + When a client calls wxDDEClient::MakeConnection(), the server receives + the message and this member is called. The application should derive a member to intercept this message and return a connection object of - either the standard wxDDEConnection type, or of a user-derived type. If the - topic is "STDIO", the application may wish to refuse the connection. - Under UNIX, when a server is created the OnAcceptConnection message is - always sent for standard input and output, but in the context of DDE - messages it doesn't make a lot of sense. + either the standard wxDDEConnection type, or of a user-derived type. + + If the @a topic is "STDIO", the application may wish to refuse the + connection. Under UNIX, when a server is created the + OnAcceptConnection() message is always sent for standard input and + output, but in the context of DDE messages it doesn't make a lot of + sense. */ virtual wxConnectionBase* OnAcceptConnection(const wxString& topic); };