X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..b5fe7ca67bf3121959a0b5a59afd00c1708f2f03:/interface/wx/ipc.h

diff --git a/interface/wx/ipc.h b/interface/wx/ipc.h
index fb477a56ac..114c6e8eda 100644
--- a/interface/wx/ipc.h
+++ b/interface/wx/ipc.h
@@ -9,47 +9,47 @@
 /**
     @class wxConnection
 
-    A wxConnection object represents the connection between a client
-    and a server. It is created by making a connection using a
-    wxClient object, or by the acceptance of a
-    connection by a wxServer object. The
-    bulk of a DDE-like (Dynamic Data Exchange) conversation is
-    controlled by calling members in a @b wxConnection object or
-    by overriding its members. The actual DDE-based implementation
-    using wxDDEConnection is available on Windows only, but a
-    platform-independent, socket-based version of this API is
+    A wxConnection object represents the connection between a client and a server.
+    It is created by making a connection using a wxClient object, or by the acceptance
+    of a connection by a wxServer object.
+
+    The bulk of a DDE-like (Dynamic Data Exchange) conversation is controlled by
+    calling members in a @b wxConnection object or by overriding its members.
+    The actual DDE-based implementation using wxDDEConnection is available on
+    Windows only, but a platform-independent, socket-based version of this API is
     available using wxTCPConnection, which has the same API.
 
-    An application should normally derive a new connection class from
-    wxConnection, in order to override the communication event
-    handlers to do something interesting.
+    An application should normally derive a new connection class from wxConnection,
+    in order to override the communication event handlers to do something interesting.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{ipc}
 
-    @see wxClient, wxServer, @ref overview_ipcoverview "Interprocess communications
-    overview"
+    @see wxClient, wxServer, @ref overview_ipc
 */
 class wxConnection : public wxObject
 {
 public:
     //@{
     /**
-        Constructs a connection object. If no user-defined connection
-        object is to be derived from wxConnection, 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 wxServer::OnAcceptConnection
-        and/or wxClient::OnMakeConnection
+        Constructs a connection object.
+
+        If no user-defined connection object is to be derived from wxConnection,
+        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 wxServer::OnAcceptConnection and/or wxClient::OnMakeConnection
         members should be replaced by functions which construct the new
         connection object.
+
         If the arguments of the wxConnection constructor are void then
         the wxConnection object manages its own connection buffer,
         allocating memory as needed. A programmer-supplied buffer cannot
         be increased if necessary, and the program will assert if it is
-        not large enough. The programmer-supplied buffer is included
-        mainly for backwards compatibility.
+        not large enough.
+
+        The programmer-supplied buffer is included mainly for backwards compatibility.
     */
     wxConnection();
     wxConnection(void* buffer, size_t size);
@@ -59,8 +59,9 @@ public:
     /**
         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.
+        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);
@@ -71,20 +72,20 @@ 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. Returns @true if successful or already disconnected.
-        The application that calls @b Disconnect must explicitly delete
+        other program; it causes the OnDisconnect() message to be sent to the
+        corresponding connection object in the other program.
+
+        Returns @true if successful or already disconnected.
+        The application that calls Disconnect() must explicitly delete
         its side of the connection.
     */
     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 OnExec()
+        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 OnExec()
         member to be called. Returns @true if successful.
     */
     bool Execute(const void* data, size_t size,
@@ -95,9 +96,8 @@ public:
     //@}
 
     /**
-        Message sent to the client application when the server notifies
-        it of a change in the data associated with the given item, using
-        Advise().
+        Message sent to the client application when the server notifies it of a
+        change in the data associated with the given item, using Advise().
     */
     virtual bool OnAdvise(const wxString& topic,
                           const wxString& item,
@@ -107,17 +107,19 @@ public:
 
     /**
         Message sent to the client or server application when the other
-        application notifies it to end the connection. The default
-        behaviour is to delete the connection object and return @true, so
-        applications should generally override @b OnDisconnect
-        (finally calling the inherited method as well) so that they know
-        the connection object is no longer available.
+        application notifies it to end the connection.
+
+        The default behaviour is to delete the connection object and return @true,
+        so applications should generally override OnDisconnect() (finally calling
+        the inherited method as well) so that they know the connection object is
+        no longer available.
     */
     virtual bool OnDisconnect();
 
     /**
         Message sent to the server application when the client notifies
         it to execute the given data, using Execute().
+
         Note that there is no item associated with this message.
     */
     virtual bool OnExec(const wxString& topic, const wxString& data);
@@ -132,12 +134,11 @@ public:
                         wxIPCFormat format);
 
     /**
-        Message sent to the server application when the client calls
-        Request(). The
-        server's OnRequest() method
-        should respond by returning a character string, or @NULL to
-        indicate no data, and setting *size. The character string must of
-        course persist after the call returns.
+        Message sent to the server application when the client calls Request().
+        The server's OnRequest() method should respond by returning a character
+        string, or @NULL to indicate no data, and setting *size.
+
+        The character string must of course persist after the call returns.
     */
     virtual const void* OnRequest(const wxString& topic,
                                   const wxString& item,
@@ -146,16 +147,16 @@ public:
 
     /**
         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
-        server can refuse to participate by returning @false.
+        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);
 
     /**
         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
-        server can refuse to stop the advise loop by returning @false, although
+        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,
@@ -164,10 +165,10 @@ public:
     //@{
     /**
         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. If size is -1 the size is computed from the string
-        length of data.
+        Can be used to transfer arbitrary data to the server.
+        Causes the server connection's OnPoke() member to be called.
+        If size is -1 the size is computed from the string length of data.
+
         Returns @true if successful.
     */
     bool Poke(const wxString& item, const void* data, size_t size,
@@ -179,32 +180,55 @@ public:
 
     /**
         Called by the client application to request data from the server.
-        Causes the server connection's OnRequest()
-        member to be called. Size may be @NULL or a pointer to a variable
-        to receive the size of the requested item.
-        Returns a character string (actually a pointer to the
-        connection's buffer) if successful, @NULL otherwise. This buffer
-        does not need to be deleted.
+        Causes the server connection's OnRequest() member to be called.
+        Size may be @NULL or a pointer to a variable to receive the size of the
+        requested item.
+
+        Returns a character string (actually a pointer to the connection's buffer)
+        if successful, @NULL otherwise. This buffer does not need to be deleted.
     */
     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.
+        Returns @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.
+        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.
     */
     bool StopAdvise(const wxString& item);
+
+    /**
+        Returns true if the format is one of the text formats.
+
+        The text formats are wxIPC_TEXT, wxIPC_UNICODETEXT and wxIPC_UTF8TEXT.
+     */
+    static bool IsTextFormat(wxIPCFormat format);
+
+    /**
+        Returns the data in any of the text formats as string.
+
+        @param data
+            The raw data pointer as used with any of the other methods of this
+            class.
+        @param size
+            The size of the data buffer pointed to by @a data.
+        @param format
+            The format of the data. It must be a text one, i.e. such that
+            IsTextFormat() returns @true for it.
+        @return
+            The string representation of the data. If the format is not text,
+            an assertion failure is triggered and empty string is returned.
+     */
+    static wxString
+    GetTextFromData(const void *data, size_t size, wxIPCFormat format);
 };
 
 
@@ -213,27 +237,24 @@ public:
     @class wxClient
 
     A wxClient object represents the client part of a client-server
-    DDE-like (Dynamic Data Exchange) conversation. The actual
-    DDE-based implementation using wxDDEClient is available on Windows
-    only, but a platform-independent, socket-based version of this
-    API is available using wxTCPClient, which has the same API.
-
-    To create a client which can communicate with a suitable server,
-    you need to derive a class from wxConnection and another from
-    wxClient. The custom wxConnection class will intercept
-    communications in a 'conversation' with a server, and the custom
-    wxClient is required so that a user-overridden
-    wxClient::OnMakeConnection
-    member can return a wxConnection of the required class, when a
-    connection is made. Look at the IPC sample and the
-    @ref overview_ipcoverview "Interprocess communications overview" for
-    an example of how to do this.
+    DDE-like (Dynamic Data Exchange) conversation.
+    The actual DDE-based implementation using wxDDEClient is available on Windows
+    only, but a platform-independent, socket-based version of this API is available
+    using wxTCPClient, which has the same API.
+
+    To create a client which can communicate with a suitable server, you need to
+    derive a class from wxConnection and another from wxClient.
+    The custom wxConnection class will intercept communications in a 'conversation'
+    with a server, and the custom wxClient is required so that a user-overridden
+    wxClient::OnMakeConnection member can return a wxConnection of the required
+    class, when a connection is made.
+
+    Look at the IPC sample and the @ref overview_ipc for an example of how to do this.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{ipc}
 
-    @see wxServer, wxConnection, @ref overview_ipcoverview "Interprocess
-    communications overview"
+    @see wxServer, wxConnection, @ref overview_ipc
 */
 class wxClient : public wxObject
 {
@@ -246,41 +267,41 @@ public:
     /**
         Tries to make a connection with a server by host (machine name
         under UNIX - use 'localhost' for same machine; ignored when using
-        native DDE in Windows), service name and topic string. If the
-        server allows a connection, a wxConnection object will be
-        returned. The type of wxConnection returned can be altered by
-        overriding the
-        OnMakeConnection()
-        member to return your own derived connection object.
+        native DDE in Windows), service name and topic string.
+
+        If the server allows a connection, a wxConnection object will be returned.
+        The type of wxConnection returned can be altered by overriding the
+        OnMakeConnection() member to return your own derived connection object.
+
         Under Unix, the service name may be either an integer port
         identifier in which case an Internet domain socket will be used
         for the communications, or a valid file name (which shouldn't
         exist and will be deleted afterwards) in which case a Unix domain
         socket is created.
-        @b SECURITY NOTE: Using Internet domain sockets if extremely
-        insecure for IPC as there is absolutely no access control for
-        them, use Unix domain sockets whenever possible!
+
+        @note Using Internet domain sockets if extremely insecure for IPC as
+              there is absolutely no access control for them, use Unix domain
+              sockets whenever possible!
     */
     wxConnectionBase* MakeConnection(const wxString& host,
                                      const wxString& service,
                                      const wxString& topic);
 
     /**
-        Called by MakeConnection(), by
-        default this simply returns a new wxConnection object. Override
-        this method to return a wxConnection descendant customised for the
-        application.
-        The advantage of deriving your own connection class is that it
-        will enable you to intercept messages initiated by the server,
-        such as wxConnection::OnAdvise. You
-        may also want to store application-specific data in instances of
+        Called by MakeConnection(), by default this simply returns a new wxConnection
+        object. Override this method to return a wxConnection descendant customised
+        for the application.
+
+        The advantage of deriving your own connection class is that it will enable
+        you to intercept messages initiated by the server, such as wxConnection::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);
 };
@@ -290,26 +311,24 @@ public:
 /**
     @class wxServer
 
-    A wxServer object represents the server part of a client-server
-    DDE-like (Dynamic Data Exchange) conversation. The actual
-    DDE-based implementation using wxDDEServer is available on Windows
-    only, but a platform-independent, socket-based version of this
-    API is available using wxTCPServer, which has the same API.
-
-    To create a server which can communicate with a suitable client,
-    you need to derive a class from wxConnection and another from
-    wxServer. The custom wxConnection class will intercept
-    communications in a 'conversation' with a client, and the custom
-    wxServer is required so that a user-overridden wxServer::OnAcceptConnection
-    member can return a wxConnection of the required class, when a
-    connection is made. Look at the IPC sample and the @ref overview_ipcoverview
-    "Interprocess communications overview" for
-    an example of how to do this.
+    A wxServer object represents the server part of a client-server DDE-like
+    (Dynamic Data Exchange) conversation. The actual DDE-based implementation
+    using wxDDEServer is available on Windows only, but a platform-independent,
+    socket-based version of this API is available using wxTCPServer, which has
+    the same API.
+
+    To create a server which can communicate with a suitable client, you need to
+    derive a class from wxConnection and another from wxServer.
+    The custom wxConnection class will intercept communications in a 'conversation'
+    with a client, and the custom wxServer is required so that a user-overridden
+    wxServer::OnAcceptConnection member can return a wxConnection of the required
+    class, when a connection is made.
+    Look at the IPC sample and the @ref overview_ipc for an example of how to do this.
 
     @library{wxbase}
-    @category{FIXME}
+    @category{ipc}
 
-    @see wxClient, wxConnection, IPC, overview()
+    @see wxClient, wxConnection, IPC, @ref overview_ipc
 */
 class wxServer
 {
@@ -320,13 +339,14 @@ public:
     wxServer();
 
     /**
-        Registers the server using the given service name. Under Unix,
-        the service name may be either an integer port identifier in
-        which case an Internet domain socket will be used for the
-        communications, or a valid file name (which shouldn't exist and
-        will be deleted afterwards) in which case a Unix domain socket is
-        created. @false is returned if the call failed (for example, the
-        port number is already in use).
+        Registers the server using the given service name.
+        Under Unix, the service name may be either an integer port identifier in
+        which case an Internet domain socket will be used for the communications,
+        or a valid file name (which shouldn't exist and will be deleted afterwards)
+        in which case a Unix domain socket is created.
+
+        @false is returned if the call failed (for example, the port number is
+        already in use).
     */
     bool Create(const wxString& service);
 
@@ -336,11 +356,11 @@ public:
         member to intercept this message and return a connection object of
         either the standard wxConnection type, or (more likely) of a
         user-derived type.
+
         If the topic is @b 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.
+        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);
 };