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.