CoPilot Navigation

iOS .NET CPIK Libraries

Contents

NOTE: Microsoft has announced it will end support for Xamarin and Xamarin.Forms on May 1, 2024. The Xamarin.Android and Xamarin.iOS platforms are now integrated directly into .NET 6 and Later. Starting with CoPilot 10.27, we have updated the CPIK libraries and sample applications for .NET Android and .NET iOS. Xamarin is still supported in CoPilot 10.27, but it will not be supported in future versions of CoPilot. To integrate CoPilot using .NET, you will need to use Visual Studio 2022 (version 17.8 or higher), .NET 8.0 or higher, and iOS 11.4 and Later.

Introduction

This guide provides details on how to get started with iOS .NET CPIK libraries. The CPIK libraries package includes the following:

Sample App

  • Source code of the sample application
  • Sample application APK that can be install on an iOS device

Libraries & Resources

  • Libs/CPIKBinding.dll: Your application uses this library to integrate CPIK libraries.
  • Native libs/CoPilotIntegrationKit.framework: Your application uses this framework alongside the CPIKBinding.dll to use the CPIK libraries.
  • Asset/copilot_resources.bundle

Note: When downloading files, be sure to download the latest version of CoPilot and to only include files from that version in your project. The .Net interface is available for the iOS platform. This interface results in all iOS compatible APIs being supported within .Net iOS. It has not been noted on individual APIs that they are also compatible on .Net via this interface as it is always true unless stated otherwise.

Sample App

Source Code

  1. Open the CPIK_Net.sln from Sample App/Source Code/CPIK_Net.sln in Visual Studio 2022. It contains all of the information required to run CoPilot (i.e. libraries, assets, etc.).
  2. You can run com.alk.CPIKNetSampleApp.ipa to install the sample app directly into the device.

Libraries & Resources

Libs /CPIKBinding.dll

This CPIKBinding.dll is a wrapper for the CPIK libraries created by using the .Net iOS Binding Library project. You need to add a reference to this library in your application.

Native libs/CoPilotIntegrationKit.framework

This is the framework containing the CPIK APIs that the CPIKWrapper.dll uses. You need to add this as a “native reference” in your project.

Assets

Copy Library and Resource/assets/copilot_resources.bundle into your project. Copy the entire assets folder located under Library and Resource/assets/ to {Your project}/Resources/ folder in your project.

The assets folder contains vital information to run CoPilot (i.e. theme, config files, skins, etc). If you have an existing assets folder in your project, please merge the content. Make sure that the entire folder under Assets is added to the .Net project and set BuildAction to BundleResource.

Library Integration instructions

Setup instructions:

  1. Reference Library & Resource/libs/ CPIKBinding.dll in your project.
  2. Reference Library & Resource/native libs/CoPilotIntegrationKit.framework in your project as a “native reference”.
  3. Extract the Library & Resource/assets/copilot_resources.bundle folder from the library package into your project (usually {Your project}/Resources/). Make sure to set BuildAction to BundleResource.

Develop!

Use the included sample application as a guide. This sample application is meant to demonstrate how to properly integrate CoPilot into your application. If you’re just getting started, take a look at MainAPIListViewController.cs and Appdelegate.cs. They demonstrate how to register and receive the callbacks as well as how to launch the different screens.

API Documentation

The API documentation detailed on this site references the classes and their members. It also contains the signature of each member of the classes, including description and usage. The documentation contains syntax for Java and Objective C. Developers can easily map the relevant syntax with C# in .Net. You can also check the syntax in .Net by exploring CPIKBinding.dll by adding a reference in your project.

Initializing CPIK libraries and Inserting the CoPilot view

The following steps show the code changes required to initialize the CPIK libraries framework and display the CoPilot navigation app by inserting its UIView into your application’s view stack. The CPIK libraries framework is accessed through a shared singleton object. The caller is not responsible for creating or managing the memory for this object. Memory will be allocated the first time the application accesses the object and will be released when the application exits.

A pointer to the CPIK libraries framework object of type CoPilot is obtained by calling the CoPilot SharedManager class method. The object returned by this method can be stored by the calling application, however memory management calls such as retain or release will have no effect on the object.

Step 1: Import the CPIK libraries header file

The file CoPilotIntegrationKit.h imports all header files necessary for working with CPIK libraries. This file should be imported in any files that will access the CPIK libraries framework. Here is an example from our sample application: 

using CoPilotIntegrationKit/CoPilotIntegrationKit
using Foundation;
using UIKit;
using System;
using System.IO;
using CoPilotIntegrationKit;
using System.Linq;

Include CoPilotIntegrationKit in any source file which uses CPIK libraries API.

Step 2: Set the CoPilot delegate and start CoPilot

The CoPilot application is started by making a call to the CoPilot instance StartNavApp() method. When this method is called, CoPilot will begin loading resources, open the GPS device, and begin drawing to its UIView.

The start-up process for CoPilot is performed on a separate thread so this method will return immediately, however the CPIK libraries API methods cannot be called until CoPilot has finished starting up. Any call to the CPIK libraries functions before CoPilot has finished initializing will result in an exception.

When CoPilot has finished initializing, it will notify the calling application calling the delegate method onCPStartup. Here is an example from the sample app. 

public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
        {
            //store temporary pointer to shared CoPilot object
            CoPilot coPilot = CoPilot.SharedManager;


            //Set the CoPilot delegate
            coPilot.WeakDelegate = this;
            coPilot.StartNavApp();


            return true;
        }

Setup CoPilot delegate and start CoPilot

And to receive the onCPStartup callback: 

[Export("onCPStartup")]
        public void OnCPStartup()
        {
            if (CallbackUtil.IsCallbackEnabled(CallbackUtil.CallbackDelegate.OnCPStartup))
                Util.DisplayMessage("", "OnCPStartup called");
        }

Step 3: Display CoPilot

The CoPilot class contains a UIViewController property named CopilotViewController which represents the root view controller of the CoPilot navigation app. This view controller can be used in your application like any other typical UIViewController. It can be displayed on the screen using the UIViewController presentViewController method, the UINavigationController PushViewController method, or any other methods that add a UIViewController to the view controller stack. 

 public partial class ViewController : UIViewController
    {


        protected ViewController(IntPtr handle) : base(handle)
        {
            // Note: this .ctor should not contain any initialization logic.
        }


        partial void ShowCP()
        {
            UIViewController cpVC = CoPilot.SharedManager.CopilotViewController;
            this.NavigationController.PushViewController(cpVC, true);
        }
}

Manipulating the CopilotViewController’s view directly is strongly discouraged, because CoPilot needs to respond to certain events, such as UIInterfaceOrientation changes, and these events are handled at the view controller level.

Last updated July 2, 2024.
Contents