Using the Components in Mac and iOS

Introduction

While the toolkits we provide include demos for Mac and iOS to show the usage of the components, the following step by step instructions will help you create your own project and configure the project to use our components in a variety of ways. This guide shows how to use the components in the following application types:

Cocoa Application

When using the Mac edition of the toolkit in your Cocoa application you will simply need to add the appropriate files for the component, as well as the library itself.

  1. In Xcode, from the project navigator create a new group called "IPWorks". This is just for organization.
  2. Right click on the group and select "Add Files to <Your Project>". Browse to the "headers" folder of the IP*Works! Installation and select the .h and .m files for the component(s) you want to use in your project. Repeat the process and browse to the "src" folder of the IP*Works! Installation and select the ipworks.cpp (the obfuscated source code).
  3. Next we need to configure the linker flags. In the Build Settings section for the project, scroll down to the "Other Linker Flags" setting. For the IP*Works! Toolkit, set the flags to -lz -lresolv Other toolkits that rely on cryptographic operations such as IP*Works! or IP*Works! SSH will need additional flags, for instance for those toolkits set the flags to -lz -lresolv -lssl -lcrypto
  4. The next step is to set the compiler language settings. In the "Build Settings" section of the project settings, find the "Apple LLVM compiler 4.1 - Language" section and change the following settings:
    • Set C Language Dialect to C99 [-std=c99]
    • Set C++ Language Dialect to Compiler Default
  5. If you are using the IP*Works! toolkit, from the "Build Phases" section of the project settings, expand the "Link Binary With Libraries" section and add:
    Security.framework
This is all that's necessary. You should be able to now code, build, and distribute your application like normal. See the demos included in the toolkit for examples using the components.

Notes About ARC (Automatic Reference Counting) Support:

In Version 9 and later: The components will automatically detect if ARC is enabled in your project. The components will work when ARC is enabled or when it is disabled without any changes on your part.

In Version 8: The components we provide are compatible with ARC, but must be converted. Alternatively you can disable ARC in the project.

Converting to Arc: To convert to ARC in Xcode navigate to Edit -> Refactor -> Convert to Objective-C ARC from Xcode.

Disabling ARC: To disable ARC, in the project settings, under "Build Settings" scroll down to "Apple LLVM compiler X.0 - Language" and set "Objective-C Automatic Reference Counting" to "No".

iOS Application

Using the components in iOS requires only a few steps as discussed below. Steps 6 and 7 are only required if you are using a toolkit which has a dependency on OpenSSL for cryptographic functions such as IP*Works! or IP*Works! SSH.

  1. In Xcode, from the project navigator create a new group called "IPWorks". This is just for organization.
  2. Right click on the group and select "Add Files to <Your Project>". Browse to the "headers" folder of the IP*Works! Installation and select the .h and .m files for the component(s) you want to use in your project. Repeat the process and browse to the "src" folder of the IP*Works! Installation and select the ipworks.cpp (the obfuscated source code).
  3. Next we need to configure the linker flags. In the Build Settings section for the project, scroll down to the "Other Linker Flags" setting. Set the flags to -lz -lresolv
  4. The next step is to set the compiler language settings. In the "Build Settings" section of the project settings, find the "Apple LLVM 5.0 - Language" section and change the following settings:
    • Set C Language Dialect to C99 [-std=c99]
    • Set C++ Language Dialect to Compiler Default
  5. Now we need to make sure the right frameworks are referenced from the project. From the "Build Phases" section of the project settings, expand the "Link Binary With Libraries" section and add:
    CFNetwork.framework
    CoreFoundation.framework
    This is all that is required for toolkits that do not rely on OpenSSL for cryptographic operations. If you are using the IP*Works! toolkit, add the following framework in the "Link Binary With Libraries" section as well:
    Security.framework
    For toolkits that do rely on OpenSSL, like IP*Works! and IP*Works! SSH, please continue reading.
  6. The following steps are only required if OpenSSL is required (i.e. SSL or SSH is in use by the product). To add support to the project for OpenSSL, right click on "Frameworks" from the project navigator and select "Add Files to ". Browse to the "openssl/lib" folder of the toolkit installation and select both the "libcrypto.a" and "libssl.a" files to add to your project.

    If your project is configured to support 64-bit (i.e. Architectures is set to "Standard Architectures (including 64-bit)") select the openssl libraries located in "openssl/lib64" instead.

  7. In the project settings, under "Build Settings", scroll down to the "Search Paths" section. Modify the "Header Search Paths" value to include the path to the "openssl/include" folder of the installation.

Notes About ARC (Automatic Reference Counting) Support:

In Version 9 and later: The components will automatically detect if ARC is enabled in your project. The components will work when ARC is enabled or when it is disabled without any changes on your part.

In Version 8: The components we provide are compatible with ARC, but must be converted. Alternatively you can disable ARC in the project.

Converting to Arc: To convert to ARC in Xcode navigate to Edit -> Refactor -> Convert to Objective-C ARC from Xcode.

Disabling ARC: To disable ARC, in the project settings, under "Build Settings" scroll down to "Apple LLVM compiler X.0 - Language" and set "Objective-C Automatic Reference Counting" to "No".

Swift support

Swift support was introduced during the lifetime of V9. To determine if your version supports Swift navigate to the installation directory and look for a folder named "swift". To include the components in a project using Swift follow the steps below.

  1. Right click the project and select "Add files" to add the required files as below.
    • .cpp file. This is the product's .cpp file found in the "src" folder of the installation. For instance "ipworks.cpp".
    • .h, .m, and .swift files These are specific to the components you wish to include and are found in the "swift" folder of the installation. For instance "IPWorksHTTP.h", "IPWorksHTTP.m", and "IPWorksHTTP.swift".

    IPWorks Files

  2. In the Build Settings section for the project, scroll down to the Other Linker Flags setting. For the IP*Works! Toolkit, set the flags to -lz -lresolv Other toolkits that rely on cryptographic operations such as IP*Works! or IP*Works! SSH will need additional flags, for instance for those toolkits set the flags to -lz -lresolv -lssl -lcrypto

    Other Linker Flags
  3. Create a bridging header file. This can have any name, such as bridging_header.h with one line for each component like:
    #import "IPWorksHTTP.h"

    Bridging Header
  4. In the Build Settings section of the project set the Objective-C Bridging Header to the bridging_header.h file created in the previous step.

    Objective-C Bridging Header
After these steps you should now be able to use the components in your Swift code. For example:

var http = IPWorksHTTPSwift()
http.get("http://www.apple.com/")
var data = http.transferredData
println(data)

iOS: Additional requirements for IP*Works! and IP*Works! SSH

The iOS versions of IP*Works! and IP*Works! SSH toolkits require OpenSSL. As a result additional steps are required.

  • Modify the Header Search Paths in the project's Build Settings to include the path to the openssl/include folder in the toolkit's installation directory.

    Header Search Paths

  • Add libssl.a and libcrypto.a to the Link Binary With Libraries section in the project's Build Phases section. These files can be found in the openssl/lib64 directory of the toolkit installation.

    Link Binary With Libraries

C++ Application using the Unix Edition (framework)

The Unix edition can be compiled on a Mac and used in an Xcode C++ application. Follow the steps below to compile and configure the Unix edition to work on your Mac.

  1. First we need to compile the library. To do this in the "src" folder of the installation type:
    make macOS_framework
    This will create a framework we can reference from Xcode. In the installation folder you should now see a Framework folder for the product. For instance for IP*Works! You should see the directory structure:
    ipworks_v8/IPWorks.framework/Versions/8.1/IPWorks
    Where "IPWorks" is the name of the framework for the product.
  2. From Xcode in the product Build Settings section, scroll down to "Header Search Paths" and add the path to the "include" folder of the installation of the toolkit.
  3. 3) Now we need to tell Xcode to link against the framework. In the Build Phases section of the project settings, under the "Link Binary With Libraries" section add a new item here. From the dialog that opens, select "Add Other.." and browse to the framework that was created on disk in step 1.
  4. Next, we need to define a macro. In the Build Settings section, scroll down to "LLVM compiler X.0 - Preprocessing" and set the Debug and Release macros to include "UNIX" (no quotes). Multiple macro values are space separated.
  5. After modifying the search path, adding the framework, and defining the UNIX macro, you should now be able to write code with the component. For instance:
    #include 
    #include 
    
    int main (int argc, const char * argv[])
    {
       HTTP http;
       http.Get("http://www.nsoftware.com");
    
       std::cout << "Hello, World!\n";
       return 0;
    }
    
    The project should also compile at this point.
  6. If you run the project now, you will notice it does not run because the framework can't be found. This due to the install name associated with the framework we built in step 1. The install name we use for IP*Works! is:
    @executable_path/../Frameworks/IPWorks.framework/Versions/8.1/IPWorks
    This means the framework needs to be copied to this location relative to where the project is actually running (for instance, in the Debug folder of the Xcode project). You can always find the install name being used by executing the command:
    otool -D IPWorks
    on the framework created in step 1, where IPWorks is the name of the framework created.
You should now be read to develop and deploy using the framework option.

C++ Application using the Unix Edition (static library)

The Unix edition can also be compiled to a static library which can be used from Xcode C++ projects. This option allows the library to be embedded in your application at compile time so you don't need to worry about deploying and managing the Framework.

The Unix edition does not need to be used in Xcode, it can be used with the gcc compiler from the command line, however the below steps focus only on using the components in Xcode.
  1. First we must compile the toolkit to get the static library (.o file). To do this from the "src" folder of the installation type:
    make
    This will create a .o file in the "src" folder. For this example, the file is "ipworks.o".
  2. Next we need to configure Xcode to look for the appropriate headers. From Xcode in the product Build Settings section, scroll down to "Header Search Paths" and add the path to the "include" folder of the installation of the toolkit.
  3. Now we need to define the UNIX macro. In the Build Settings section, scroll down to "LLVM compiler X.0 - Preprocessing" and set the Debug and Release macros to include "UNIX" (no quotes). Multiple macro values are space separated.
  4. Lastly we need to link with the appropriate libraries. From the Build Phases section, under the "Link Binary With Libraries" section add a new item here. From the dialog that opens, select "Add Other.." and browse to the .o file that was created on disk in step 1. We will also need to add the libraries and frameworks that the product depends on. After adding the .o file, add another library and this time look in the list for:
    libresolv
    libz
    Other toolkits such as IP*Works! SSH and IP*Works! will also require:
    libssl
    libcrypto
    Add the following frameworks as well:
    CoreFoundation.framework
    CoreServices.framework
  5. You should now be able to write code, compile, and run your project using our components

We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.

 
 
Downloads