About the MBS Xojo Network Kit 2. NSConnection Wrapper 3. NSNetService Wrapper 4. Interfaces 5. NetworkKitUtilityModule 5. NSNetServiceBrowserMB 6

Transcription

1 MBS Xojo Network Kit Version 1.0, 2015 by Christian Schmitz About the MBS Xojo Network Kit 2 NSConnection Wrapper 3 NSNetService Wrapper 4 Interfaces 5 NetworkKitUtilityModule 5 NSNetServiceBrowserMB 6 NSNetServiceMB 7 NSErrorMB 9 NSURLConnectionMB 10 NSURLRequestMB 11 NSMutableURLRequestMB 15 NSURLResponseMB 18 NSURLConnectionMemoryMB 20 NSURLConnectionFileMB 21 Version History 22 Known issues 22 Installation 23 Requirements 24 License 25 Contact 26 1 of 26

2 About the MBS Xojo Network Kit The MBS Xojo Network Kit provides you with a few useful classes and modules to easily use network functions in ios. The Kit contains: Wrapper for OS X and ios Bonjour classes to publish service and browser for service including resolving the IP addresses. Wrapper for OS X and ios for NSConnection classes including NSURLRequest/ NSURLResponse with HTTP extensions. Common code for Cocoa base classes in the NetworkKitUtilityModule module. 2 of 26

3 NSConnection Wrapper The Network Kit contains a wrapper for NSConnection, Apple's Cocoa interface for download on OS X and ios: Features HTTP and HTTPS support. FTP download support Synchronously and asynchronously transfers Load to memory or file Supply HTTP Header fields Supply HTTP Body for upload Supply HTTP Method like GET, PUT, POST or others. Control about cache handling Can use pipelining with HTTP 1.1 Define if to use cellular network or not. Wrapper Features For Xojo 2015r1 Using exception handling to track error Test code included All classes with MB postfix to avoid name conflicts. Compiles for all targets All module definitions are protected to avoid conflicts Inline documentation Full Source code, no encryption Works for 32bit and 64bit targets. Example projects for Desktop, ios and Console using our classes. Future features we could add: Support for password authentication. Add NSURLSession classes. 3 of 26

4 NSNetService Wrapper The Network Kit contains a wrapper for NSNetService and NSNetServiceBrowser, Apple's Cocoa interface for Bonjour on OS X and ios: Features asynchronously browses for domains to use asynchronously browses for services with given type asynchronously publishes services query/publish TXT Record data. Function to check for events on console projects. Parse code for IP addresses, supporting IPv4 and IPv6 Wrapper Features For Xojo 2015r1 Using exception handling to track error Test code included All classes with MB postfix to avoid name conflicts. Compiles for all targets All module definitions are protected to avoid conflicts Inline documentation Full Source code, no encryption Works for 32bit and 64bit targets. Example projects for Desktop, Web, ios and Console using our classes. Future features we could add: TXT Record parse/create functions. didacceptconnectionwithinputstreamoutputstream event 4 of 26

5 Interfaces NetworkKitUtilityModule Module NetworkKitUtilityModule Protected Sub AddToDelegateMap(handle as integer, o as object) Protected Function AllocateObject(ClassRef as Integer) As integer Protected Sub CheckEvents() for console only runs runloop for one round to check for events Protected Sub CheckForMainThread() Protected Sub CheckRunLoop(ServiceHandle as integer) Protected Function ClassName(handle as integer) As Text get class name of a handle Protected Function GetEmpyNSStringHandle() As Integer Protected Function GetInstanceForHandle(Handle as Integer) As Object Protected Function Init(handle as integer) As integer Protected Function IsTextVariant(v as Variant) As Boolean Protected Function MemoryBlockCStringToText(m as memoryblock) As text Protected Function MemoryBlockToNSData(m as MemoryBlock) As integer Protected Function MemoryBlockToPtr(m as memoryblock) As ptr Protected Function NSClassFromText(Name as Text) As Integer Protected Function NSDataLength(NSDataRef as Integer) As UInt64 Protected Function NSDataToMemoryBlock(NSDataRef as Integer) As MemoryBlock Protected Function NSDataToString(NSDataRef as Integer) As string Protected Function NSDictionaryFromDictionary(dic as Dictionary) As Integer converts Dictionary with only Text/String to NSDictionary Protected Function NSDictionaryFromDictionary(dic as xojo.core.dictionary) As Integer converts Dictionary with only Text/String to NSDictionary Protected Function NSDictionaryToDictionary(NSDictionaryRef as Integer) As Dictionary converts Dictionary with only NSString to Xojo Dictionary Protected Function NSInputStreamFromPath(Path as String) As Integer Protected Function NSInputStreamFromPath(Path as Text) As Integer Protected Function NSInputStreamFromURL(URL as Text) As Integer Protected Function NSInputStreamFromURL(URL as string) As Integer Protected Function NSSelectorFromString(Name as string) As Integer Protected Function NSSelectorFromText(Name as Text) As Integer Protected Function NSURLFromText(URL as String) As Integer Protected Function NSURLFromText(URL as Text) As Integer Protected Function NSURLPath(NSURLHandle as integer) As text Protected Function NSURLToText(NSURLHandle as integer) As text Protected Sub ReleaseHandle(handle as integer) Protected Sub RemoveFromDelegateMap(handle as integer) Protected Function RetainCount(Handle as Integer) As integer Protected Function RetainHandle(handle as integer) As integer Protected Function TextToMemoryBlock(t as text) As memoryblock End Module 5 of 26

6 NSNetServiceBrowserMB domain. NSNetService Class NSNetServiceBrowserMB ComputedProperty Description As text description for debugging ComputedProperty includespeertopeer As Boolean Initially set to false. Set to true to also browse over peer to peer Bluetooth and Wi-Fi (if available). Must be set before starting to search. Initially set to false. Set to true to also browse over peer to peer Bluetooth and Wi-Fi (if available). Must be set before starting to search. Const NSNetServicesActivityInProgress = Const NSNetServicesBadArgumentError = Const NSNetServicesCancelledError = Const NSNetServicesCollisionError = Const NSNetServicesInvalidError = Const NSNetServicesNotFoundError = Const NSNetServicesTimeoutError = Const NSNetServicesUnknownError = Sub CheckEvents() for console only runs runloop for one round to check for events Sub Constructor() Sub Constructor(Handle as Integer) Sub Destructor() Sub searchforbrowsabledomains() Starts a search for domains that are browsable via Bonjour and the computer's network configuration. Discovered domains are reported to the DidFindDomain event. There may be more than one browsable Sub searchforregistrationdomains() Starts a search for domains in which the network configuration allows registration (i.e. publishing). Most NSNetServiceBrowser clients do not need to use this API, as it is sufficient to publish an instance with the empty string (see -[NSNetService initwithdomain:type:name:port:]). Discovered domains are reported to the DidFindDomain event. There may be more than one registration domain. Sub searchforservicesoftype(type as text, domain as text = "") Starts a search for services of the specified type in the domain indicated by domainstring. For each service discovered, a foundservice event is raised. Sub stop() Stops the currently running search. End Class 6 of 26

7 NSNetServiceMB Class NSNetServiceMB ComputedProperty Description As text ComputedProperty TXTRecordData As MemoryBlock Sets the TXT record of the NSNetService instance that has been or will be published. Pass nil to remove the TXT record from the instance. Returns the raw TXT record of the NSNetService instance. If the instance has not been resolved, or the DidUpdateTXTRecordData event has not been called, this will return nil. It is permitted to have a zero-length TXT record. ComputedProperty addressipv4 As text get first IPv4 address ComputedProperty addressipv6 As text get first IPv6 address ComputedProperty classname As text ComputedProperty domain As text Returns the domain of the discovered or published service. ComputedProperty hostname As text Returns the DNS host name of the computer hosting the discovered or published service. If a successful resolve has not yet occurred, this method will return "". ComputedProperty includespeertopeer As Boolean Initially set to false. Set to true to also publish, resolve, or monitor this service over peer to peer Bluetooth and Wi-Fi (if available). Must be set before operation starts. Initially set to false. Set to true to also publish, resolve, or monitor this service over peer to peer Bluetooth and Wi-Fi (if available). Must be set before operation starts. ComputedProperty name As text Returns the name of the discovered or published service. ComputedProperty port As Integer The port of a resolved service. This returns -1 if the service has not been resolved. ComputedProperty type As text Returns the type of the discovered or published service. Const NSNetServiceListenForConnections = 2 Const NSNetServiceNoAutoRename = 1 Const NSNetServicesActivityInProgress = Const NSNetServicesBadArgumentError = Const NSNetServicesCancelledError = Const NSNetServicesCollisionError = Const NSNetServicesInvalidError = Const NSNetServicesNotFoundError = Const NSNetServicesTimeoutError = Const NSNetServicesUnknownError = Sub CheckEvents() for console only runs runloop for one round to check for events Sub Constructor(Handle as Integer) init with handle Sub Constructor(s as NSNetServiceMB) 7 of 26

8 put an existing service in a new object, e.g. to handle events Sub Constructor(domain as text, type as text, name as text) This is the initializer for resolution. If you know the domain, type and name of the service for which you wish to discover addresses, you should initialize an NSNetService instance using this method and call resolve on the result. Sub Constructor(domain as text, type as text, name as text, port as integer) This is the initializer for publishing. You should use this initializer if you are going to announce the availability of a service on the network. To publish a service in all available domains, pass the empty string as the domain. Sub Destructor() Function addresses(ipv4 as Boolean = true, IPv6 as Boolean = true) As text() The addresses of the service. pass IPv4 or IPv6 as false to filter list Sub publish() Advertises a given service on the network. This method returns immediately. Success or failure is indicated by callbacks to the NSNetService instance's delegate. Sub publish(options as integer) Advertises a given service on the network. This method returns immediately. Success or failure is indicated by callbacks to the NSNetService events. See the notes above for NSNetServiceNoAutoRename for information about controlling the autorenaming behavior using this method. Sub resolve() Attempts to determine at least one address for the NSNetService instance. For applications linked on or after Mac OS X 10.4 "Tiger", this method calls resolvewithtimeout with a value of 5.0. Sub resolve(timeout as Double) Starts a resolve for the NSNetService instance of the specified duration. If the DidResolveAddress event is called before the timeout expires, the resolve is successful. If the timeout is reached, the DidNotResolve event will be called. The value of the NSNetServicesErrorCode key in the error dictionary will be NSNetServicesTimeoutError. Sub startmonitoring() Starts monitoring the NSNetService instance for events. In Mac OS X 10.4 Tiger, monitored NSNetService instances inform their delegates of changes to the instance's TXT record by calling the DidUpdateTXTRecordData event. Sub stop() Halts a service which is either publishing or resolving. Sub stopmonitoring() Stops monitoring the NSNetService instance for events. Property Handle As Integer End Class 8 of 26

9 NSErrorMB Class NSErrorMB ComputedProperty code As integer get error code ComputedProperty domain As text get error domain ComputedProperty localizeddescription As text get localized error description Sub Constructor(Handle as Integer) Sub Destructor() Property Handle As Integer End Class 9 of 26

10 NSURLConnectionMB Class NSURLConnectionMB ComputedProperty currentrequest As NSURLRequestMB new in Mac OS X 10.8 and ios 5.0 ComputedProperty originalrequest As NSURLRequestMB new in Mac OS X 10.8 and ios 5.0 Sub Destructor() cleanup Shared Function canhandlerequest(request as NSURLRequestMB) As Boolean Sub cancel() cancel transfer Shared Function sendsynchronousrequest(request as NSURLRequestMB, byref response as NSURLResponseMB, byref Error as NSErrorMB) As MemoryBlock Performs a synchronous load of the given request, returning an NSURLResponse in the given out parameter. Sub start() starts transfer Note "About" This is the base class for NSURLConnection. Property Handle As Integer Property IsLoading As Boolean Property TotalSize As Int64 Property done As Boolean End Class 10 of 26

11 NSURLRequestMB Class NSURLRequestMB ComputedProperty HTTPBody As MemoryBlock Returns the request body data of the receiver. This data is sent as the message body of the request, as in done in an HTTP POST request. The request body data of the receiver. ComputedProperty HTTPMethod As text Returns the HTTP request method of the receiver. ComputedProperty HTTPShouldHandleCookies As Boolean Decide whether default cookie handling will happen for this request. True if cookies should be sent with and set for this request; otherwise false. The default is true - in other words, cookies are sent from and stored to the cookie manager by default. ComputedProperty HTTPShouldUsePipelining As Boolean Reports whether the receiver is not expected to wait for the previous response before transmitting. True if the receiver should transmit before the previous response is received. False if the receiver should wait for the previous response before transmitting. ComputedProperty TimeoutInterval As double get timeout in seconds ComputedProperty URL As text Returns the URL of the receiver. ComputedProperty allhttpheaderfields As Dictionary Queries the HTTP header fields of the receiver to the given dictionary. This method replaces all header fields that may have existed before this method call. Since HTTP header fields must be string values, each object and key in the dictionary passed to this method must be text. If either the key or value for a key-value pair is not text when sent this message, the key-value pair is skipped. ComputedProperty allowscellularaccess As Boolean returns whether a connection created with this request is allowed to use the built in cellular radios (if present). True if the receiver is allowed to use the built in cellular radios to satify the request, false otherwise. ComputedProperty cachepolicy As NSURLRequestCachePolicy Returns the cache policy of the receiver. ComputedProperty maindocumenturl As text The main document URL associated with this load. This URL is used for the cookie "same domain as main document" policy. There may also be other future uses. See setting MainDocumentURL In the current implementation, this value is unused by the framework. A fully functional version of this method will be available in the future. ComputedProperty networkservicetype As NSURLRequestNetworkServiceType Returns the NSURLRequestNetworkServiceType associated with this request. This will return NSURLNetworkServiceTypeDefault for requests that have not explicitly set a networkservicetype (using the NetworkServiceType setter). The NSURLRequestNetworkServiceType associated with this request. Enum NSURLRequestCachePolicy NSURLRequestUseProtocolCachePolicy = 0 NSURLRequestReloadIgnoringLocalCacheData = 1 11 of 26

12 NSURLRequestReturnCacheDataElseLoad = 2 NSURLRequestReturnCacheDataDontLoad = 3 NSURLRequestReloadIgnoringCacheData = 1 End Enum Enum NSURLRequestNetworkServiceType NSURLNetworkServiceTypeDefault = 0 NSURLNetworkServiceTypeVoIP = 1 NSURLNetworkServiceTypeVideo = 2 NSURLNetworkServiceTypeBackground = 3 NSURLNetworkServiceTypeVoice = 4 End Enum Sub Constructor(Handle as Integer) create request with given handle Sub Constructor(URL as text) Allocates and initializes an NSURLRequest with the given URL. Default values are used for cache policy (NSURLRequestUseProtocolCachePolicy) and timeout interval (60 seconds). Sub Constructor(URL as text, cachepolicy as NSURLRequestCachePolicy, timeoutinterval as Double) Allocates and initializes a NSURLRequest with the given URL and cache policy. Sub Destructor() Shared Function Tests() As MemoryBlock some tests if things work in general Function copy() As NSURLRequestMB creates a copy of the request Function mutablecopy() As NSMutableURLRequestMB Creates a mutable copy of this request Shared Sub testmessage(s as text) Function valueforhttpheaderfield(field as text) As text Returns the value which corresponds to the given header field. Note that, in keeping with the HTTP RFC, HTTP header field names are case-insensitive. field the header field name to use for the lookup (case-insensitive). the value associated with the given header field, or empty text if there is no value associated with the given header field. Note "About" NSURLRequest This class file describes the constructs used to represent URL load requests in a manner independent of protocol and URL scheme. Immutable and mutable variants of this URL load request concept are described, named NSURLRequest and NSMutableURLRequest, respectively. A collection of constants is also declared to exercise control over URL content caching policy. NSURLRequest and NSMutableURLRequest are designed to be customized to support protocol-specific requests. enum NSURLRequestCachePolicy The NSURLRequestCachePolicy enum defines constants that can be used to specify the type of interactions that take place with the caching system when the URL loading system processes a request. Specifically, these constants cover interactions that have to do with whether already-existing cache data is returned to satisfy a URL load request. NSURLRequestUseProtocolCachePolicy Specifies that the caching logic defined in the protocol implementation, if any, is used for a particular URL load request. This is the default policy for URL load requests. NSURLRequestReloadIgnoringLocalCacheData Specifies that the data for the URL load should be loaded from the origin source. No existing local cache data, regardless of its freshness or validity, should be used to satisfy a URL load request. 12 of 26

13 NSURLRequestReloadIgnoringLocalAndRemoteCacheData Specifies that not only should the local cache data be ignored, but that proxies and other intermediates should be instructed to disregard their caches so far as the protocol allows. Unimplemented. NSURLRequestReloadIgnoringCacheData Older name for NSURLRequestReloadIgnoringLocalCacheData. NSURLRequestReturnCacheDataElseLoad Specifies that the existing cache data should be used to satisfy a URL load request, regardless of its age or expiration date. However, if there is no existing data in the cache corresponding to a URL load request, the URL is loaded from the origin source. NSURLRequestReturnCacheDataDontLoad Specifies that the existing cache data should be used to satisfy a URL load request, regardless of its age or expiration date. However, if there is no existing data in the cache corresponding to a URL load request, no attempt is made to load the URL from the origin source, and the load is considered to have failed. This constant specifies a behavior that is similar to an "offline" NSURLRequestReloadRevalidatingCacheData Specifies that the existing cache data may be used provided the origin source confirms its validity, otherwise the URL is loaded from the origin source. Unimplemented. enum NSURLRequestNetworkServiceType The NSURLRequestNetworkServiceType enum defines constants that can be used to specify the service type to associate with this request. The service type is used to provide the networking layers a hint of the purpose of the request. NSURLNetworkServiceTypeDefault Is the default value for an NSURLRequest when created. This value should be left unchanged for the vast majority of requests. NSURLNetworkServiceTypeVoIP Specifies that the request is for voice over IP control traffic. NSURLNetworkServiceTypeVideo Specifies that the request is for video traffic. NSURLNetworkServiceTypeBackground Specifies that the request is for background traffic (such as a file download). NSURLNetworkServiceTypeVoice Specifies that the request is for voice data. NSURLRequest An NSURLRequest object represents a URL load request in a manner independent of protocol and URL scheme. NSURLRequest encapsulates two basic data elements about a URL load request: * The URL to load. * The policy to use when consulting the URL content cache made available by the implementation. In addition, NSURLRequest is designed to be extended to support protocol-specific data by adding categories to access a property object provided in an interface targeted at protocol implementors. 13 of 26

14 Objects of this class are used to create NSURLConnection instances, which can are used to perform the load of a URL, or as input to the NSURLConnection class method which performs synchronous loads. Property Handle As Integer End Class 14 of 26

15 NSMutableURLRequestMB Class NSMutableURLRequestMB Inherits NSURLRequestMB ComputedProperty HTTPBody As MemoryBlock Sets the request body data of the receiver. This data is sent as the message body of the request, as in done in an HTTP POST request. Value: the new request body data for the receiver. Returns the request body data of the receiver. This data is sent as the message body of the request, as in done in an HTTP POST request. The request body data of the receiver. ComputedProperty HTTPMethod As text Sets the HTTP request method of the receiver. Returns the HTTP request method of the receiver. ComputedProperty HTTPShouldHandleCookies As Boolean Decide whether default cookie handling will happen for this request. True if cookies should be sent with and set for this request; otherwise false. The default is true - in other words, cookies are sent from and stored to the cookie manager by default. Decide whether default cookie handling will happen for this request. True if cookies should be sent with and set for this request; otherwise false. The default is true - in other words, cookies are sent from and stored to the cookie manager by default. ComputedProperty HTTPShouldUsePipelining As Boolean Sets whether the request should not wait for the previous response before transmitting. True if the receiver should transmit before the previous response is received. False to wait for the previous response before transmitting. Calling this method with a true value does not guarantee HTTP pipelining behavior. This method may have no effect if an HTTP proxy is configured, or if the HTTP request uses an unsafe request method (e.g., POST requests will not pipeline). Pipelining behavior also may not begin until the second request on a given TCP connection. There may be other situations where pipelining does not occur even though YES was set. HTTP 1.1 allows the client to send multiple requests to the server without waiting for a response. Though HTTP 1.1 requires support for pipelining, some servers report themselves as being HTTP 1.1 but do not support pipelining (disconnecting, sending resources misordered, omitting part of a resource, etc.). Reports whether the receiver is not expected to wait for the previous response before transmitting. True if the receiver should transmit before the previous response is received. False if the receiver should wait for the previous response before transmitting. ComputedProperty TimeoutInterval As Double Sets the timeout interval of the receiver. The timeout interval specifies the limit on the idle interval allotted to a request in the process of loading. The "idle interval" is defined as the period of time that has passed since the last instance of load activity occurred for a request that is in the process of loading. Hence, when an instance of load activity occurs (e.g. bytes are received from the network for a request), the idle interval for a request is reset to 0. If the idle interval ever becomes greater than or equal to the timeout interval, the request is considered to have timed out. This timeout interval is measured in seconds. value: The new timeout interval in seconds of the receiver. 15 of 26

16 other future uses. get timeout in seconds ComputedProperty URL As text Sets the URL of the receiver. Returns the URL of the receiver. ComputedProperty allhttpheaderfields As Dictionary Sets the HTTP header fields of the receiver to the given dictionary. This method replaces all header fields that may have existed before this method call. Since HTTP header fields must be string values, each object and key in the dictionary passed to this method must be text. If either the key or value for a key-value pair is not text when sent this message, the key-value pair is skipped. value: a dictionary containing HTTP header fields. Queries the HTTP header fields of the receiver to the given dictionary. This method replaces all header fields that may have existed before this method call. Since HTTP header fields must be string values, each object and key in the dictionary passed to this method must be text. If either the key or value for a key-value pair is not text when sent this message, the key-value pair is skipped. ComputedProperty allowscellularaccess As Boolean sets whether a connection created with this request is allowed to use the built in cellular radios (if present). allow false if the receiver should not be allowed to use the built in cellular radios to satisfy the request, true otherwise. The default is true. returns whether a connection created with this request is allowed to use the built in cellular radios (if present). True if the receiver is allowed to use the built in cellular radios to satify the request, false otherwise. ComputedProperty cachepolicy As NSURLRequestCachePolicy sets the cache policy of the receiver. Returns the cache policy of the receiver. ComputedProperty maindocumenturl As text Sets the main document URL URL The main document URL. The caller should pass the URL for an appropriate main document, if known. For example, when loading a web page, the URL of the main html document for the top-level frame should be passed. This main document will be used to implement the cookie "only from same domain as main document" policy, and possibly other things in the future. NOTE: In the current implementation, the passed-in value is unused by the framework. A fully functional version of this method will be available in the future. The main document URL associated with this load. This URL is used for the cookie "same domain as main document" policy. There may also be See setting MainDocumentURL In the current implementation, this value is unused by the framework. A fully functional version of this method will be available in the future. ComputedProperty networkservicetype As NSURLRequestNetworkServiceType Sets the NSURLRequestNetworkServiceType to associate with this request networkservicetype The NSURLRequestNetworkServiceType to associate with the request. This method is used to provide the network layers with a hint as to the purpose of the request. Most clients should not need to use this method. 16 of 26

17 Returns the NSURLRequestNetworkServiceType associated with this request. This will return NSURLNetworkServiceTypeDefault for requests that have not explicitly set a networkservicetype (using the NetworkServiceType setter). The NSURLRequestNetworkServiceType associated with this request. Sub Constructor() create new empty request Sub Constructor(theHandle as Integer) create request with given handle Sub Constructor(URL as text) Allocates and initializes an NSURLRequest with the given URL. Default values are used for cache policy (NSURLRequestUseProtocolCachePolicy) and timeout interval (60 seconds). Sub Constructor(URL as text, cachepolicy as NSURLRequestCachePolicy, timeoutinterval as Double) Allocates and initializes a NSURLRequest with the given URL and cache policy. Sub ValueForHTTPHeaderField(field as text, assigns value as text) for assignment like this: x.valueforhttpheaderfield(field) = value Sub addvalueforhttpheaderfield(field as text, value as text) Adds an HTTP header field in the current header dictionary. This method provides a way to add values to header fields incrementally. If a value was previously set for the given header field, the given value is appended to the previously-existing value. The appropriate field delimiter, a comma in the case of HTTP, is added by the implementation, and should not be added to the given value by the caller. Note that, in keeping with the HTTP RFC, HTTP header field names are case-insensitive. Sub sethttpbodywithfile(file as FolderItem) Sets the request body to be the contents of the given file. The entire file's contents will be transmitted as the HTTP body of the request. Note that the body stream and the body data (set by HTTPBody) are mutually exclusive setting one will clear the other. Sub sethttpbodywithpath(path as Text) Sets the request body to be the contents of the given file. The entire file's contents will be transmitted as the HTTP body of the request. Note that the body stream and the body data (set by HTTPBody) are mutually exclusive setting one will clear the other. Sub sethttpbodywithurl(url as text) Sets the request body to be the contents of the given file. The entire file's contents will be transmitted as the HTTP body of the request. Note that the body stream and the body data (set by HTTPBody) are mutually exclusive setting one will clear the other. Sub setvalueforhttpheaderfield(field as text, value as text) Sets the value of the given HTTP header field. If a value was previously set for the given header field, that value is replaced with the given value. Note that, in keeping with the HTTP RFC, HTTP header field names are case-insensitive. Note "About" class NSMutableURLRequest An NSMutableURLRequest object represents a mutable URL load request in a manner independent of protocol and URL scheme. End Class This specialization of NSURLRequest is provided to aid developers who may find it more convenient to mutate a single request object for a series of URL loads instead of creating an immutable NSURLRequest for each load. This programming model is supported by the following contract stipulation between NSMutableURLRequest and NSURLConnection: NSURLConnection makes a deep copy of each NSMutableURLRequest object passed to one of its initializers. 17 of 26

18 NSURLResponseMB Class NSURLResponseMB ComputedProperty MIMEType As text Returns the MIME type of the receiver. The MIME type is based on the information provided from an origin source. However, that value may be changed or corrected by a protocol implementation if it can be determined that the origin server or source reported the information incorrectly or imprecisely. An attempt to guess the MIME type may be made if the origin source did not report any such information. ComputedProperty URL As text Returns the URL of the receiver. ComputedProperty allheaderfields As Dictionary Returns a dictionary containing all the HTTP header fields of the receiver. By examining this header dictionary, clients can see the "raw" header information which was reported to the protocol implementation by the HTTP server. This may be of use to sophisticated or special-purpose HTTP clients. Returns a dictionary containing all the HTTP header fields of the receiver. ComputedProperty expectedcontentlength As Int64 Returns the expected content length of the receiver. ComputedProperty statuscode As Integer Returns the HTTP status code of the receiver. ComputedProperty suggestedfilename As text Returns a suggested filename if the resource were saved to disk. ComputedProperty textencodingname As text Returns the name of the text encoding of the receiver. Sub Constructor(Handle as Integer) create new response with given handle Sub Constructor(URL as text, StatusCode as Integer, HTTPVersion as Text, HeaderFields as Dictionary) Initializer for NSHTTPURLResponse objects. Sub Constructor(URL as text, MIMEType as text, expectedcontentlength as Integer, textencodingname as text) Initialize an NSURLResponse with the provided values. Sub Destructor() the Destructor Function copy() As NSURLResponseMB creates a copy of the object Shared Function localizedstringforstatuscode(statuscode as Integer) As text Convenience method which returns a localized string corresponding to the status code for this response. the status code to use to produce a localized string. returns a localized string corresponding to the given status code. Note "About" An NSURLResponse object represents a URL load response in a manner independent of protocol and URL scheme. NSURLResponse encapsulates the metadata associated with a URL load. Note that NSURLResponse objects do not contain the actual bytes representing the content of a URL. See NSURLConnection and NSURLConnectionDelegate for more information about receiving the content data for a URL load. An NSHTTPURLResponse object represents a response to an HTTP URL load. It is a specialization of NSURLResponse which provides conveniences for accessing information specific to HTTP 18 of 26

19 protocol responses. Property Handle As Integer End Class 19 of 26

20 NSURLConnectionMemoryMB Class NSURLConnectionMemoryMB Inherits NSURLConnectionMB Sub Constructor(Handle as Integer) creates connection with given handle Sub Constructor(request as NSURLRequestMB) creates connection with given request Sub Constructor(request as NSURLRequestMB, startimmediately as Boolean) creates connection with given request and optionally starts it directly Note "About" This is the NSURLConnectionMB subclass to handle memory based downloads -> download to MemoryBlock -> download and write yourself to socket, binarystream, serialport or whatever use NSURLConnectionFileMB to download to file directly Property CollectData As Boolean // whether to collect data for this download Property Data As xojo.core.mutablememoryblock // the memoryblock where we collect data End Class 20 of 26

21 NSURLConnectionFileMB Class NSURLConnectionFileMB Inherits NSURLConnectionMB Sub Constructor(Handle as Integer) creates connection with given handle Sub Constructor(request as NSURLRequestMB) creates connection with given request Sub Constructor(request as NSURLRequestMB, startimmediately as Boolean) creates connection with given request and optionally starts it directly Note "About" This is the NSURLConnectionMB subclass to handle file based downloads database. End Class use NSURLConnectionMemoryMB to download to MemoryBlock or write data yourself to a file or 21 of 26

22 Version History Tip: If you want to update your existing code with new release, you d best compare projects with Arbed ( and copy modifications to your project. 1.1, beta Fixed bugs in documentation. 1.0, first release Known issues NSConnection file download returns a file URL where we don t have a file. 22 of 26

23 Installation To get your projects working with this Network Kit, you need to follow a few steps. Drop the folder externals into your project and access all the modules and classes. Or copy from existing example projects what you need. 23 of 26

24 Requirements You need Xojo 2015r1 or newer. We did not test with older versions, but you can if you need. If you need network functions for Windows, Linux and Mac OS X cross platform, please check our MBS Plugins, especially the Network and CURL plugin parts. For Linux you can use MBS Linux Plugin with avahi classes. 24 of 26

25 License Summary: You may use Network Kit only with one licensed Xojo installation. You agree not to share the Network Kit or use someone else's Network Kit copy. Christian Schmitz Software GmbH, of Nickenich Germany is the owner, developer and sole copyright holder of this product, which is licensed -not sold- to you on a non-exclusive basis. You agree not to share your MBS Xojo Network Kit with anyone. You may transfer your license to another person only after receiving written authorization from Christian Schmitz Software GmbH and only if the recipient agrees to be bound by the terms of this agreement. Christian Schmitz Software GmbH reserves the right to cancel the license key(s) of any user who Christian Schmitz Software GmbH determines is in violation of this agreement. THE WARRANTIES IN THIS AGREEMENT REPLACE ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING ANY WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE IS PROVIDED "AS IS" AND Christian Schmitz Software GmbH DISCLAIMS AND EXCLUDES ALL OTHER WARRANTIES. IN NO EVENT WILL Christian Schmitz Software GmbH BE LIABLE FOR ANY SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, EVEN IF WE HAVE KNOWLEDGE OF THE POTIENTIAL LOSS OR DAMAGE. If you are located in Germany this agreement is subject to the laws of Germany. If you are located outside Germany local law may apply. Some states do not allow the exclusion of warranties, so the above exclusion may not apply to you. Christian Schmitz Software GmbH does not charge royalties or deployment fees for Xojo applications. Access to updates is included for one year. After that time you can order an update or keep using the old version you have. 25 of 26

26 Contact Christian Schmitz Software GmbH Eckertshohl Nickenich Germany Phone: (Office) or (Mobile) 26 of 26