// 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
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
{
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.
*/
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
{
/**
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,
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();
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();
//@{
/**
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);
/**
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);
/**
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,
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,
/**
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,
//@{
/**
- 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);
//@}
/**
- 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);
};
projects / wxWidgets.git / blobdiff