X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/adaaa68635b4c8a4d8c5284add40366ea3eefb07..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/sckipc.h diff --git a/interface/wx/sckipc.h b/interface/wx/sckipc.h index 6da6f56e4e..719a6ea4be 100644 --- a/interface/wx/sckipc.h +++ b/interface/wx/sckipc.h @@ -3,9 +3,39 @@ // Purpose: interface of wxTCPServer // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + +/** + See wxTCPConnection. +*/ +enum wxIPCFormat +{ + wxIPC_INVALID = 0, + wxIPC_TEXT = 1, /* CF_TEXT */ + wxIPC_BITMAP = 2, /* CF_BITMAP */ + wxIPC_METAFILE = 3, /* CF_METAFILEPICT */ + wxIPC_SYLK = 4, + wxIPC_DIF = 5, + wxIPC_TIFF = 6, + wxIPC_OEMTEXT = 7, /* CF_OEMTEXT */ + wxIPC_DIB = 8, /* CF_DIB */ + wxIPC_PALETTE = 9, + wxIPC_PENDATA = 10, + wxIPC_RIFF = 11, + wxIPC_WAVE = 12, + wxIPC_UTF16TEXT = 13, /* CF_UNICODE */ + wxIPC_ENHMETAFILE = 14, + wxIPC_FILENAME = 15, /* CF_HDROP */ + wxIPC_LOCALE = 16, + wxIPC_UTF8TEXT = 17, + wxIPC_UTF32TEXT = 18, + wxIPC_UNICODETEXT, + wxIPC_PRIVATE = 20 +}; + + /** @class wxTCPServer @@ -16,9 +46,9 @@ A DDE-based implementation for Windows is available using wxDDEServer. @library{wxnet} - @category{FIXME} + @category{net} - @see wxTCPClient, wxTCPConnection, @ref overview_ipcoverview "IPC overview" + @see wxTCPClient, wxTCPConnection, @ref overview_ipc */ class wxTCPServer : public wxObject { @@ -29,19 +59,22 @@ public: wxTCPServer(); /** - 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 is already in use). + 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 is already in use). */ virtual 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 - member to intercept this message and return a connection object of - either the standard wxTCPConnection type, or of a user-derived type. If the - topic is "STDIO", the application may wish to refuse the connection. + 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 wxTCPConnection 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. */ @@ -59,18 +92,17 @@ public: A DDE-based implementation for Windows is available using wxDDEClient. - To create a client which can communicate with a suitable server, - you need to derive a class from wxTCPConnection and another from wxTCPClient. + To create a client which can communicate with a suitable server, you need + to derive a class from wxTCPConnection and another from wxTCPClient. The custom wxTCPConnection class will intercept communications in a 'conversation' with a server, and the custom wxTCPServer is required - so that a user-overridden wxTCPClient::OnMakeConnection member can return + so that a user-overridden wxTCPClient::OnMakeConnection() member can return a wxTCPConnection of the required class, when a connection is made. @library{wxnet} - @category{FIXME} + @category{net} - @see wxTCPServer, wxTCPConnection, @ref overview_ipcoverview "Interprocess - communications overview" + @see wxTCPServer, wxTCPConnection, @ref overview_ipc */ class wxTCPClient : public wxObject { @@ -82,12 +114,13 @@ public: /** Tries to make a connection with a server specified by the host - (a machine name under Unix), service name (must - contain an integer port number under Unix), and a topic string. If the - server allows a connection, a wxTCPConnection object will be returned. + (a machine name under Unix), service name (must contain an integer + port number under Unix), and a topic string. + + If the server allows a connection, a wxTCPConnection object will be returned. + The type of wxTCPConnection returned can be altered by overriding - the OnMakeConnection() member to return your own - derived connection object. + the OnMakeConnection() member to return your own derived connection object. */ virtual wxConnectionBase* MakeConnection(const wxString& host, const wxString& service, @@ -98,10 +131,11 @@ public: be altered by deriving the @b OnMakeConnection member to return your own derived connection object. By default, a wxTCPConnection 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 wxTCPConnection::OnAdvise. You may also want to - store application-specific data in instances of the new class. + as wxTCPConnection::OnAdvise(). You may also want to store + application-specific data in instances of the new class. */ virtual wxConnectionBase* OnMakeConnection(); @@ -123,36 +157,37 @@ public: A DDE-based implementation for Windows is available using wxDDEConnection. A wxTCPConnection object can be created by making a connection using a - wxTCPClient object, or by the acceptance of a connection by a - wxTCPServer object. The bulk of a conversation is controlled by - calling members in a @b wxTCPConnection object or by overriding its - members. + wxTCPClient object, or by the acceptance of a connection by a wxTCPServer object. + The bulk of a conversation is controlled by calling members in a + @b wxTCPConnection object or by overriding its members. An application should normally derive a new connection class from wxTCPConnection, in order to override the communication event handlers to do something interesting. @library{wxnet} - @category{FIXME} + @category{net} - @see wxTCPClient, wxTCPServer, @ref overview_ipcoverview "Interprocess - communications overview" + @see wxTCPClient, wxTCPServer, @ref overview_ipc */ class wxTCPConnection : public wxObject { public: //@{ /** - Constructs a connection object. If no user-defined connection object is - to be derived from wxTCPConnection, 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 wxTCPServer::OnAcceptConnection - and/or wxTCPClient::OnMakeConnection members should be replaced by - functions which construct the new connection object. If the arguments of - the wxTCPConnection 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 + Constructs a connection object. + + If no user-defined connection object is to be derived from wxTCPConnection, + 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 wxTCPServer::OnAcceptConnection and/or wxTCPClient::OnMakeConnection + members should be replaced by functions which construct the new connection object. + + If the arguments of the wxTCPConnection constructor are void, then a default + buffer is associated with the connection. Otherwise, the programmer must + provide a buffer and size of the buffer for the connection object to use in transactions. */ wxTCPConnection(); @@ -162,9 +197,11 @@ 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. + the data associated with the given item. + + Causes the client connection's OnAdvise() member to be called. + + Returns @true if successful. */ bool Advise(const wxString& item, const void* data, size_t size, wxIPCFormat format = wxIPC_PRIVATE); @@ -175,22 +212,25 @@ 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 + 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. + side of the connection having called @b Disconnect. + + Returns @true if successful. */ virtual 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. + + Returns @true if successful. */ bool Execute(const void* data, size_t size, wxIPCFormat format = wxIPC_PRIVATE); @@ -211,15 +251,15 @@ public: /** Message sent to the client or server application when the other - application notifies it to delete the connection. Default behaviour is - to delete the connection object. + application notifies it to delete the connection. + Default behaviour is to delete the connection object. */ virtual bool OnDisconnect(); /** Message sent to the server application when the client notifies it to - execute the given data. Note that there is no item associated with - this message. + execute the given data. + Note that there is no item associated with this message. */ virtual bool OnExecute(const wxString& topic, const void* data, size_t size, @@ -235,9 +275,9 @@ public: 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, + 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. */ virtual const void* OnRequest(const wxString& topic, @@ -247,16 +287,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, @@ -264,10 +304,9 @@ 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. Returns @true if successful. + 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. */ bool Poke(const wxString& item, const void* data, size_t size, wxIPCFormat format = wxIPC_PRIVATE); @@ -277,26 +316,28 @@ 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 + 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. */ - const void* Request(const wxString& item, size_t* size, + virtual const void* Request(const wxString& item, size_t* size = 0, 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. + with the server. + + Causes the server connection's OnStartAdvise() member to be called. + Returns @true if the server okays it, @false otherwise. */ virtual 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. */ virtual bool StopAdvise(const wxString& item); };