When you want to submit data to a web service, there are several different approaches that you can take in your applications. Code which was written using older versions of SocketTools would simply use the PostData method, or HttpPostData function in the API. With the current version, you have additional options.
The PostData Method
In earlier versions of SocketTools, there was only one way to submit payload data to a web service, and that was using the PostData method or HttpPostData function. It is a general use method which can issue a POST request and provide any kind of data payload provided.
It accepts either a string or byte array as the payload and will perform the appropriate encoding based on the encoding type specified for the session. By default, most form-based payloads would require URL encoding and the content type would be specified as "application/x-www-form-urlencoded".
Here is a simple example using the SocketTools.HttpClient .NET class:
var _client = new SocketTools.HttpClient();
string _payload = "This is a simple text payload";
string _response = "";
if (_client.PostData("https://test.sockettools.com/postdata", _payload, ref _response))
{
Console.WriteLine(_response);
}
In this example, a request is being sent to our test server at test.sockettools.com with a simple text payload. Because there are no options set, it will be URL encoded and submitted using POST. The response from the server will be returned in a string, and in this case, will contain some diagnostic output, along with a hex dump of the payload which was submitted:
Request Payload (39 bytes) 0x0000 : 54 68 69 73 25 32 30 69 73 25 32 30 61 25 32 30 : This%20is%20a%20 0x0010 : 73 69 6D 70 6C 65 25 32 30 74 65 78 74 25 32 30 : simple%20text%20 0x0020 : 70 61 79 6C 6F 61 64 00 00 00 00 00 00 00 00 00 : payload.........
What if the service does not expect the payload to be URL encoded? This is usually the case today where the request payload consists of XML or JSON formatted data. You would do this by setting the Encoding property prior to submitting the request (or in the case of the library API, calling the HttpSetEncodingType function).
var _client = new SocketTools.HttpClient();
string _payload = "This is a simple text payload";
string _response = "";
// Set the encoding type to encodingNone to prevent URL encoding
// and inform the server about the payload type
_client.Encoding = HttpClient.HttpEncoding.encodingNone;
_cleint.SetHeader("Content-Type", "text/plain");
if (_client.PostData("https://test.sockettools.com/postdata", _payload, ref _response))
{
Console.WriteLine(_response);
}
Now the payload does not contain any encoding when it's sent to the server for processing:
Request Payload (29 bytes) 0x0000 : 54 68 69 73 20 69 73 20 61 20 73 69 6D 70 6C 65 : This.is.a.simple 0x0010 : 20 74 65 78 74 20 70 61 79 6C 6F 61 64 00 00 00 : .text.payload...
There is also a special XML encoding type which would use URL encoding, except spaces would not be encoded. However, most services today which expect an XML payload will not use this (and in fact, will not recognize URL encoding at all).
PostData and Unicode Strings
The PostData method can accept both byte arrays and string buffers as the payload which will be submitted to the server. When a byte array is provided, the data is sent as-is without any modification. When a Unicode string contains the payload, it will be automatically encoded as UTF-8 text prior to being submitted.
This is an important consideration when sending text which contains non-ASCII characters because what is sent may not be identical to what is received by the server. Any character outside of the standard ASCII range will be encoded as a multi-byte character sequence which can represent the Unicode characters in the string.
Most web services expect text to use UTF-8 encoding and this does not present a problem in typical use cases. Legacy web services which do not support UTF-8 may expect text to use a specific ANSI character set, such as ISO-Latin 1 and in that case, your application will need to convert your Unicode string into a byte array using that specific character set, and then provide the byte array as the payload argument.
In .NET, refer to the System.Text.Encoding related classes to help perform that conversion. With the ActiveX controls, you can use the StrConv function in Visual Basic to convert a string to a byte array. With C/C++ you can use the WideCharToMultiByte function to perform the conversion.
In summary, if you are working with string data and want to prevent it from being sent as UTF-8 encoded text, convert it to a byte array first and that ensures it will be submitted "as is" to the server.
PostJson and PostXml
To make things a bit simpler when submitting JSON and XML formatted payloads, the current version of SocketTools includes two methods named, as expected, PostJson and PostXml. The API includes equivalent functions named HttpPostJson and HttpPostXml.
These work similarly to PostData and HttpPostData, however they do a few important things which eliminates some extra coding which would otherwise be required:
The JSON and XML payloads are automatically encoded as UTF-8 text, making it safe to submit data which contains Unicode characters.
The Content-Type request header is automatically set for the correct content type. For JSON payloads it will be set to "application/json" and for XML it will be set to "text/xml". You can override those values if you wish using the SetHeader method or HttpSetRequestHeader function, but it is not recommended.
The default encoding type is set to "none" so the data will not be submitted using the same URL encoding method common to form-related payloads. This is expected by virtually every RESTful web service today.
Here is an example of a simple JSON request using the .NET class:
var _client = new SocketTools.HttpClient();
string _jsonPayload = @"{ ""name"": ""John Smith"", ""age"": 35 }";
string _response = "";
if (_client.PostJson("https://test.sockettools.com/postjson", _jsonPayload, ref _response))
{
Console.WriteLine(_response);
}
As you can see, this involves a bit less code and makes it clear exactly what your application is doing (in this case, submitting a JSON request to the server).
To help you test your code, we have the test.sockettools.com server which can be used to test and help debug different types of requests, including the most common GET, POST and PUT operations.
See Also
Using the SocketTools Test Server
Automatic URL Redirection
Unicode Support in SocketTools