.. _c-api-intro:

============
Introduction
============

:Author:    Stefan Eletzhofer
:Date:      2012-09-29

Abstract
========

This chapter aims to provide a short overview of the C-API.

Calling Convention
==================

The library uses the *C calling convention* and consumes and produces
*C-like null terminated strings*.

Common Flow
===========

The common flow to use any call of the library is:

- allocate a nxfs handle using `nxfs_alloc()`

- set the Windchill base URL and credentials using `nxfs_set_url()`

- allocate a location handle using `nxfs_loc_alloc()`

- call the desired functionality using the handles created

- free the location handle using `nxfs_loc_free()`

- free nxfs handle using `nxfs_free()`

Logging
=======

To aid debugging in case of client-side issues, the library facilitates a
very basic logging system.

If you find that the library behaves strange, increase the log level and
set the log file name::

    #import "nxfileservice.h"

    ...

    nxfs_loglevel(1);  // increase for more details, 0 silences.
    nxfs_logfile("nxfs.log");

The log file written contains all function calls and their return codes,
and additional status information.  The content of the file, and a error
description is most often sufficient to solve a issue.

.. warning:: Turn **off** logging in production.  Never log for a extended
   amount of time, as the log files grow unbounded.  Log files contain
   security relevant information -- keep them secure!

Examples
========

As a picture is more than thousand words, we'll provide some short
examples.

A short word on error handling -- all calls return a integer status.  A
status value of `0` indicates no error, everything else is an error.  It is
the caller's responsibility to check for errors.  For the sake of brevity,
we'll not show this in the examples below.

Initializing a file service handle
----------------------------------

To initialize a `nxfs_h` handle, you do::

    nxfs_h *nxfs = NULL;
    nxfs_alloc(&nxfs);

To free the handle, do::

    nxfs_free(&nxfs);

Setting the Windchill URL and credentials
-----------------------------------------

To set base URL and credentials, do::

    nxfs_set_url(nxfs, "http://www.example.com/Windchill", "username", "password");

Listing the files of a document
-------------------------------

To list all the files stored inside a specific document, you
need to know the **document name**, and the **context name**.  The library
captures this information in a *location handle*::

  nxfs_loc_h *location = NULL;
  nxfs_loc_alloc(&location, "AProductName", "SomeDocumentName");

Then you'll get all the files, one by one, which are captured in a
`nxfs_fileinfo_t` type like so::

  nxfs_fileinfo_t *info = NULL;
  nxfs_list_files(nxfs, location, &info);
  while (info) {
    printf("filename=%s", pInfo->pFilename);
    printf("mimetype=%s", pInfo->pMimetype);
    printf("role=%s", pInfo->pRole);
    printf("size=%ld", pInfo->size);

    nxfs_list_files_next(nxfs, location, &info);
  }

Fetching the contents of a file
-------------------------------

To get the *contents* of a file which **filename** you know, do::

  nx_buffer_t *content = NULL;
  nx_buf_alloc(&content);

  nxfs_file_get(nxfs, location, "somefile.txt", content);

  printf("file content:\n%s\n", content->buffer);

  nx_buf_free(&content);

Posting a file to the server
----------------------------

Uploading a file to the Windchill server in this context means **adding
secodary content** to a Windchill Business Object.

First, we need the file content in a `buffer` object::

    nx_buffer_t *content = NULL;

    nx_buf_alloc(&content);

    fd = open("filename.ext", O_RDONLY);
    nx_buf_fromfile(content, fd);
    close(fd);


Next, we're telling the library to post the content to the server.  We're
also telling it that we want a new iteration of the business object and
supply a test message for the iteration.  The result of the post operation
will be placed in a `nxfs_post_result_t` which we also need to pass::

    nxfs_post_result_t result;
    nxfs_file_post(nxfs, location, "a file name.ext", content, 1, "test message", &result);

Remember, that the `location` is a handle which identifies the Business
Object we're operating on.

The `result` will now contain the new `oid` of the Business Object, and the
`success` state, which should be non-zero now::

    printf("oid=%s", result.oid);
    printf("success=&s", result.success?"YES":"NO");

The above sequence is suitable if you want to uplaod **one** file.  If you
want to upload a bunch of files, then it's better to first check-out the
Business Object and specifying `0` for the `iterate` parameter at
`nxfs_file_post()` above.  This way, you'll get **one** iteration with all
your changes.

.. note:: There's not yet a C-level function call for checking out a business
    object.  This will be fixed.

.. vim: set ft=rst tw=75 nocin nosi ai sw=4 ts=4 spell expandtab: