About this plugin
This plugin can turn your publications into simple and easy to use TCP/IP servers and clients. You can prepare your publication to act like a server, a client or both at the same time, allowing you to send ASCII text from servers to clients and viceversa.
The plugin is based on the native and well tested Windows Winsock(tm) and don't require any thirdty party file or DLL. Follow the philosophy of my other npMsgs plugin, but in this case you can communicate publications situated on differents computers around the world.
Thirparty
This plugin are imposible without the aid of this people:
Thanks a lot!
Create a new instance of an Talk server object. The result variable store the ID (a numeric value) of the created server object. You need this identifier in order to use the others plugin actions.
Destroy a previously created instanace of an Talk server object. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Active (listen for clients) the specified instance of the Talk server object. Specity the ID of the previously created server object and use this action to active the server. Also specify the port of the server, and, remember that the same port cannot be used for two servers at the same time. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Deactive (from listen for clients) the specified instance of the Talk server object. If any client are connected to the server, the appropiate npOnTalkClientDisconnect event. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Find if the specified Talk server is active (listen for clients) or not. The result variable store "True" if the server is active or "False" if not. Also, the result variable can store "False" if an error occur. On this last case the [LastError] contain information about the possible error.
Send text to one or all Talk clients from the specified Talk server object. This action can be used to send ASCII text to one or all connected clients. If you specify some client IP, the text are only send to the appropiate client IP. If let the Client IP variable blank the text are send to all connected clients. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Please note: even when the plugin do not impose a limiation in the ammount of text which can be send I carefully recommend you not to send text larger than above 200 KB. If you need to send an entire file remember you can upload to an FTP server, for example, and then send the URL of such file to your receiver.
Set a subroutine to be executed when the specified Talk server object read event is fired. This event is fired when some connected client send text to the server. You can use the the Socket variable in order to get the received text and other information of the client socket connection. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Set a subroutine to be executed when the specified Talk server object error event is fired. The Socket variable store information about the possible error and about the client socket connection. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Set a subroutine to be executed when the specified Talk server object listen event is fired. This event is fired when the server are put in "listen" mode, that is, just after execute the npTalkServerActive action if no error occurs. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error. Also, remember to take a look at the Socket variable.
Set a subroutine to be executed when the specified Talk server object accept event is fired. This event is fired after npOnTalkServerConnect when the client finally is accepted on the server. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error. Also, remember to take a look at the Socket variable.
Set a subroutine to be executed when the specified Talk server object connect event is fired. This event is fired when a client is trying to connect to the server, before the npOnTalkServerAccept event is executed. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error. Also, remember to take a look at the Socket variable.
Set a subroutine to be executed when the specified Talk server object disconnect event is fired. This event is fired when a client is disconnected from the server. The Socket variable provide you information about the client socket connection, like the client IP. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Create a new instance of an Talk client object. The result variable store the ID (a numeric value) of the created client object. You need this identifier in order to use the others plugin actions.
Destroy a previously created instanace of an Talk client object. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Active (connect to a server) the specified instance of the Talk client object. Providing the appropiate Server IP and Server port this action try to establish a connection with the server. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Deactive (disconnect from a server) the specified instance of the Talk client object. Use this action to disconnect the client from the server. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Find if the specified Talk client is active (connected to a server) or not. The result variable store "True" if the client is active or "False" if not. Also, the result variable can store "False" if an error occur. On this last case the [LastError] contain information about the possible error.
Send text to the server of the specified active (connected) Talk client object. This action can be used to send ASCII text to the connected server. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Please note: even when the plugin do not impose a limiation in the ammount of text which can be send I carefully recommend you not to send text larger than above 200 KB. If you need to send an entire file remember you can upload to an FTP server, for example, and then send the URL of such file to your receiver.
Set a subroutine to be executed when the specified Talk client object read event is fired. This event is fired when the connected server send text to the client. You can use the the Socket variable in order to get the received text and other information of the server socket connection. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Set a subroutine to be executed when the specified Talk client object error event is fired. The Socket variable store information about the possible error and about the server socket connection. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error.
Set a subroutine to be executed when the specified Talk client object connect event is fired. This event is fired when the client is connected to the server. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error. Also, remember to take a look at the Socket variable.
Set a subroutine to be executed when the specified Talk client object connecting event is fired. This event is fired when the client is trying to connect with the server. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error. Also, remember to take a look at the Socket variable.
Set a subroutine to be executed when the specified Talk client object disconnect event is fired. The result variable store "True" if everything is OK, or "False" when not. On this last case the [LastError] contain information about the possible error. Also, remember to take a look at the Socket variable.
All of this plugins events, for both Talk servers and Talk clients objects, put at your service a Socket variable. You can name this variable as usual, for example, "Socket", or "MySocket", etc. The name of the variable are used for the prefix, and then, the plugin do the rest preparing various prefixed variables. Here is the list of all possible variables derived from the Socket variable:
Since the TCP protocol do not guarantee our data is transfer in just one piece, and therefore we need to implement some kind of "message end" search to join (if needed) the received data, npTalk implement an internal buffer to make this TCP behaviour transparent for you. In other words, when an npTalk client or server send an string, the plugin append to the string two special characters (ASCII #6 and #7) and then, when an npTalk client or server receive an string, the plugin looking for that characters and do not fire the appropiate event until they are found into the received data and therefore consider that the transmission is complete.
This is the default and the recommended behaviour of the npTalk plugin and works like expected if you use npTalk clients and servers, which is the general purpose of the npTalk plugin. However, if you want to connect an (non npTalk) TCP client with an npTalk server, for example, maybe you can adapt such TCP client in order to append the refered characters to the sended data, but maybe you can't do it and therefore your TCP client cannot send the data appropiatelly and the npTalk server cannot read it well. To avoid this scenario the plugin put available the [npTalkDontUseInternalBuffer] global variable.
If you plain to use npTalk clients and servers, you no need to worry about this variable at all. But, if you want to setup an npTalk server which do not use their normal internal buffer, simply set that variable to "True" before create the npTalk server object. After that momment the server do not append the refered characters into their sended string, and do not expect for any characters when receive some data over TCP. The same can be said for npTalk clients: you can set "True" the refered variable before create the client object to inform the plugin you do not want to use the default internal buffer.
WARNING: If you do not use the plugin internal buffer, it's your responsability to take care about the received data. Generally you receive all the data in just one piece, and then you no need to worry about. But if this is not possible (due to the TCP protocol) you are responsible to know when a received message end. Since this is a bit difficult and can overload your NeoBook publication the plugin implement the internal buffer by default, so use the refered variable carefully and only if you really need to combine non npTalk based client or server with npTalk based client or server.
All the NeoPlugins deal with errors in the same way that NeoBook does: when the plugin found an action error the [LastError] variable store information about the error, so you can take care about this variable when execute an action.
But all the NeoPlugins also incorporate an advanced way to deal with possible action errors. You can define a subroutine named OnNeoPluginActionError in order to be executed when some action error are found and you can use this variables inside:
Note that this error handling subroutine are shared for all the NeoPlugins, so you no need to specify a subroutine for every plugin you use in your publication because the same subroutine are recognized and automagically used by every NeoPlugin. Below you can view a sample of this subroutine code:
:OnNeoPluginActionError AlertBox "NeoPlugin Error" "Error [LastError] in plugin: [PluginName]" Return
Also note that the use of this NeoPlugins error handling subroutine is completelly optional. You can continue using the [LastError] variable as usual and even use the both methods at the same time.