MATLAB Production Server C Client  R2017a
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
client.h
Go to the documentation of this file.
1 /**
2  Copyright (C) 2015 The MathWorks, Inc.
3 */
4 #ifndef MATHWORKS_MPS_CLIENT
5 #define MATHWORKS_MPS_CLIENT
6 
7 #define MPS_CLIENT_1_0 0x00010000
8 #define MPS_CLIENT_1_1 0x00010001
9 
10 #ifndef MPS_MAX_VER
11 #define MPS_MAX_VER MPS_CLIENT_1_1
12 #endif
13 
14 #ifdef _MSC_VER
15  #define MPS_DLL_EXPORT_SYM __declspec(dllexport)
16  #define MPS_DLL_IMPORT_SYM __declspec(dllimport)
17 #elif __GNUC__ >= 4
18  #define MPS_DLL_EXPORT_SYM __attribute__ ((visibility("default")))
19  #define MPS_DLL_IMPORT_SYM __attribute__ ((visibility("default")))
20 #else
21  #define MPS_DLL_EXPORT_SYM
22  #define MPS_DLL_IMPORT_SYM
23 #endif
24 
25 #if defined(BUILDING_MPSCLIENT)
26 #define MPSCLIENT_PUBLISHED_API MPS_DLL_EXPORT_SYM
27 #else
28 #define MPSCLIENT_PUBLISHED_API MPS_DLL_IMPORT_SYM
29 #endif
30 
31 #ifdef __cplusplus
32 #define MPSCLIENT_PUBLISHED_API_EXTERN_C extern "C" MPSCLIENT_PUBLISHED_API
33 #else
34 #define MPSCLIENT_PUBLISHED_API_EXTERN_C extern MPSCLIENT_PUBLISHED_API
35 #endif
36 
37 #include <limits.h>
38 
39 #ifdef _MSC_VER
40 typedef unsigned __int64 uint64;
41 #else
42 #include <stddef.h>
43 #include <stdint.h>
44 typedef uint64_t uint64;
45 #endif
46 
47 /** Type that represents size values, such as array dimensions. */
48 typedef uint64 mpsSize;
49 
50 /** Type that represents index values, such as indices into arrays. */
51 typedef uint64 mpsIndex;
52 
53 /** Fundamental type underlying MATLAB data. Use any of the <c>mpsCreate</c> functions to create
54  data, and the corresponding <c>mpsDestroyArray</c> function to free memory. */
55 typedef struct mpsArray mpsArray;
56 
57 /** Structure containing information configuring the connection between the client and a
58  server instance.
59  \sa <c>mpsClientRuntime</c>
60 */
62 
63 /** Establishes a connection between a client and a server.
64  An instance of <c>mpsClientContext</c> should not be shared across multiple threads at the
65  same time. In a multi-threaded environment, each thread should get its own instance of
66  <c>mpsClientContext</c>.
67  \sa <c>mpsClientRuntime</c>
68 */
70 
71 #ifndef TMW_BITS_PER_INT
72 # if INT_MAX == 0x7FL
73 # define TMW_BITS_PER_INT 8
74 # elif INT_MAX == 0x7FFFL
75 # define TMW_BITS_PER_INT 16
76 # elif INT_MAX == 0x7FFFFFFFL
77 # define TMW_BITS_PER_INT 32
78 # else
79 # define TMW_BITS_PER_INT -1
80 # endif
81 #endif
82 
83 #ifndef TMW_BITS_PER_LONG
84 # if LONG_MAX == 0x7FL
85 # define TMW_BITS_PER_LONG 8
86 # elif LONG_MAX == 0x7FFFL
87 # define TMW_BITS_PER_LONG 16
88 # elif LONG_MAX == 0x7FFFFFFFL
89 # define TMW_BITS_PER_LONG 32
90 # else
91 # define TMW_BITS_PER_LONG -1
92 # endif
93 #endif
94 
95 #ifndef TMW_BITS_PER_SCHAR
96 # if SCHAR_MAX == 0x7FL
97 # define TMW_BITS_PER_SCHAR 8
98 # elif SCHAR_MAX == 0x7FFFL
99 # define TMW_BITS_PER_SCHAR 16
100 # elif SCHAR_MAX == 0x7FFFFFFFL
101 # define TMW_BITS_PER_SCHAR 32
102 # else
103 # define TMW_BITS_PER_SCHAR -1
104 # endif
105 #endif
106 
107 #ifndef TMW_BITS_PER_SHRT
108 # if SHRT_MAX == 0x7FL
109 # define TMW_BITS_PER_SHRT 8
110 # elif SHRT_MAX == 0x7FFFL
111 # define TMW_BITS_PER_SHRT 16
112 # elif SHRT_MAX == 0x7FFFFFFFL
113 # define TMW_BITS_PER_SHRT 32
114 # else
115 # define TMW_BITS_PER_SHRT -1
116 # endif
117 #endif
118 
119 #ifndef UINT16_T
120 # if TMW_BITS_PER_INT == 16
121 # define UINT16_T unsigned int
122 # elif TMW_BITS_PER_LONG == 16
123 # define UINT16_T unsigned long
124 # elif TMW_BITS_PER_SCHAR == 16
125 # define UINT16_T unsigned char
126 # elif TMW_BITS_PER_SHRT == 16
127 # define UINT16_T unsigned short
128 # endif
129 #endif
130 
131 #if (defined(__cplusplus) && (__cplusplus >= 201103L)) || (defined(_HAS_CHAR16_T_LANGUAGE_SUPPORT) && _HAS_CHAR16_T_LANGUAGE_SUPPORT)
132 typedef char16_t CHAR16_T;
133 #elif defined(_MSC_VER)
134 typedef wchar_t CHAR16_T;
135 #else
136 typedef UINT16_T CHAR16_T;
137 #endif
138 
140 
141 #if !defined(__cplusplus)
142 
143 typedef unsigned char bool;
144 
145 #ifndef false
146 #define false (0)
147 #endif
148 #ifndef true
149 #define true (1)
150 #endif
151 
152 #endif
153 
154 /** Type for logical array. All logical <c>mpsArray</c>s store their data elements as
155  <c>mpsLogical</c> rather than as <c>bool</c>. */
156 typedef bool mpsLogical;
157 
158 /** Types of errors that can be thrown when MATLAB function invocation fails */
159 typedef enum mpsErrorInfoType {
160 
161  /** A non-200 HTTP response when MATLAB function in invoked from the client */
163 
164  /** A MATLAB execution error */
166 
167  /** Any error other than MATLAB execution error or a non-200 HTTP response */
169 
171 
172 
173 /** Details about a non-200 HTTP response */
174 typedef struct mpsErrorInfoHTTP {
175 
176  /** HTTP response code */
177  unsigned int responseCode;
178 
179  /** HTTP response message */
180  const char* responseMessage;
181 
183 
184 
185 /** Entry in the MATLAB runtime stack */
186 typedef struct matlabStackFrame {
187 
188  /** Name of the MATLAB file that threw the MATLAB error */
189  const char* file;
190 
191  /** Name of the MATLAB function which in most cases is same as the MATLAB file name */
192  const char* function;
193 
194  /** Line number in the MATLAB file where the error occurred */
195  int line;
196 
198 
199 
200 /** Details about a MATLAB execution error */
201 typedef struct mpsErrorInfoMATLAB {
202 
203  /** Error message corresponding to the error thrown in MATLAB */
204  const char* message;
205 
206  /** Unique error identifier corresponding to the MATLAB error */
207  const char* identifier;
208 
209  /** MATLAB stack associated with the MATLAB error */
211 
212  /** Number of entries in the MATLAB stack */
214 
216 
217 /** Details about an error not caused by non-200 HTTP errors or MATLAB execution errors */
218 typedef struct mpsErrorInfoGeneric {
219 
220  /** Error message corresponding to the generic error */
221  const char* genericErrorMsg;
222 
224 
225 
226 /** Error thrown when a MATLAB function is invoked by the MATLAB Production Server client context */
227 typedef struct mpsErrorInfo {
228 
229  /** Type of underlying error */
231 
232  /** Message regarding the error */
233  char const* message;
234 
235  /** All possible errors that can be thrown when a MATLAB function is invoked from the client */
236  union {
237  /** Error caused by a non-200 HTTP response */
239 
240  /** Error thrown during execution of MATLAB code */
242 
243  /** Error other than MATLAB execution error and non-200 HTTP response */
245  } details;
246 
247 } mpsErrorInfo;
248 
249 /** Error status codes for all methods which are part of the MATLAB Production Server client API */
250 typedef enum mpsStatus {
251 
252  /** Successful invocation of a method */
254 
255  /** Failure */
257 
258 } mpsStatus;
259 
260 /** Flag specifying whether array has imaginary components */
261 typedef enum mpsComplexity {
262  /** Identifies an <c>mpsArray</c> with no imaginary components. */
264  /** Identifies an <c>mpsArray</c> with imaginary components. */
266 } mpsComplexity;
267 
268 /** Flag identifying class of array */
269 typedef enum mpsClassID {
270  /** Identifies a numeric <c>mpsArray</c> whose data is stored as either <c>unsigned char</c> or <c>byte</c>. */
272  /** Identifies a numeric <c>mpsArray</c> whose data is stored as either <c>char</c> or <c>byte</c>. */
274  /** Identifies a numeric <c>mpsArray</c> whose data is stored as <c>unsigned short</c>. */
276  /** Identifies a numeric <c>mpsArray</c> whose data is stored as <c>short</c>. */
278  /** Identifies a numeric <c>mpsArray</c> whose data is stored as <c>unsigned int</c>. */
280  /** Identifies a numeric <c>mpsArray</c> whose data is stored as <c>int</c>. */
282  /** Identifies a numeric <c>mpsArray</c> whose data is stored as <c>unsigned long long</c>. */
284  /** Identifies a numeric <c>mpsArray</c> whose data is stored as <c>long long</c>. */
286  /** Identifies a numeric <c>mpsArray</c> whose data is stored as <c>float</c>. */
288  /** Identifies a numeric <c>mpsArray</c> whose data is stored as <c>double</c>. */
290  /** Identifies a logical <c>mpsArray</c>. */
292  /** Identifies a string <c>mpsArray</c>. */
294  /** Identifies a structure <c>mpsArray</c>. */
296  /** Identifies a cell <c>mpsArray</c>. */
298 } mpsClassID;
299 
300 /** MATLAB Production Server client API container.
301  <c>mpsClientRuntime</c> provides functions needed to create the MATLAB Production Server client execution context,
302  configure it, and use the execution context to execute MATLAB functions hosted by an MATLAB Production Server
303  instance.
304 */
305 typedef struct mpsClientRuntime {
306 
307  /** Initialize pointer to MATLAB Production Server client configuration instance with default values.
308  The configuration parameters are used to configure the connection between
309  client and MATLAB Production Server instance.
310  Currently, the only parameter that can be initialized is the response timeout
311  in seconds. This is the time the client will wait for the MATLAB Production Server instance to
312  send the response. The default value is 120 seconds.
313  @param config An uninitialized pointer to MATLAB Production Server client configuration instance.
314  @return Status representing whether client configuration initialization was
315  successful.
316  */
318 
319  /** Clean up the memory allocated to the client configuration instance
320  @param config Pointer to the client configuration that needs to be cleaned up
321  */
322  void (*destroyConfig) (mpsClientConfig* config);
323 
324  /** Set the timeout value, in seconds, for the client to receive response from the server.*/
325  void (*setResponseTimeOutSec) (mpsClientConfig* config, unsigned long value);
326 
327  /** Get the timeout value, in seconds, for the client to receive response from the server */
328  unsigned long (*getResponseTimeOutSec)(const mpsClientConfig* config);
329 
330  /** Set the response size limit value, in bytes, for the client.*/
331  void (*setResponseSizeLimit) (mpsClientConfig* config, unsigned int value);
332 
333  /** Get the responze size limit value, in bytes, for the client. */
334  unsigned int (*getResponseSizeLimit)(const mpsClientConfig* config);
335 
336  /** Initialize the MATLAB Production Server client execution context.
337  Execution context is initialized with the configuration parameters passed using
338  MATLAB Production Server client configuration instance. The execution context encapsulates the HTTP framework
339  required to execute MATLAB functions from the client. It also manages the connections
340  between the client and the server instance. The execution context makes copy of the configuration
341  being passed. As a result, the configuration pointer does not need to be kept around
342  in the client application once the execution context has been created.
343  You should use one execution context for every thread and it should not be shared across
344  multiple threads.
345  @param context Uninitialized memory location of pointer to the client context
346  @param config Pointer to the client-server connection configuration
347  */
349 
350  /** Clean up the memory allocated for the client execution context.
351  This function cleans up all the resources used while invoking MATLAB functions
352  from the client e.g the container for holding the last error. It also closes
353  all the open connections between the client and the server instance created
354  by the client execution context. Once destroyed, the execution context cannot be used to invoke MATLAB functions.
355  @param context Pointer to the client context
356  */
357  void (*destroyContext) (mpsClientContext* context);
358 
359  /** Access the error thrown while invoking a MATLAB function from the client
360  A MATLAB function invocation failure can happen due to one of the following reasons:
361  1. MATLAB function threw an error
362  2. Client received a response code other than 200
363  3. Failure due to connection issues between the client and MATLAB Production Server instance
364  The purpose of this function is to provide detailed information about the root cause of the failure.
365  This function should be invoked only when the return status of MATLAB function invocation is a
366  non-success status. Invoking this method when the MATLAB function invocation is successful will result
367  in a undefined behaviour.
368  @param context MATLAB Production Server client context used to invoke the MATLAB function
369  @param errorInfo Struct containing detailed information regarding failed MATLAB function invocation
370  */
371  void (*getLastErrorInfo) (mpsClientContext const* context, mpsErrorInfo* errorInfo);
372 
373  /** Cleans up dynamic memory allocated while initializing mpsErrorInfo instance
374  */
375  void (*destroyLastErrorInfo) (mpsErrorInfo* errorInfo);
376 
377  /** Invoke MATLAB function hosted by a server instance and available at a Url.
378  MATLAB Production Server clients invoke MATLAB functions hosted by a server instance using
379  a Url with the following format:
380  `http://<hostname>:<port_number>/<archive_name>/<MATLAB_function_name>`.
381 
382  The following Url exposes the MATLAB function `mymagic` deployed in `magic.ctf` at port
383  9910 localhost.
384 
385  http://localhost:9910/magic/mymagic
386 
387  The inputs and outputs are of type `mpsArray`.
388 
389  If the return status of this function is not success, the root cause of the failure is accessed
390  by invoking `getLastErrorInfo()`.
391  @param context Client context that holds a handle to the underlying HTTP framework instance
392  @param url Url to the MATLAB function
393  @param nlhs Number of outputs (number of left hand side parameters)
394  @param plhs Pointer to the output
395  @param nrhs Number of input arguments (number of right hand side parameters)
396  @param prhs Pointer to the inputs
397  @return Status of execution.
398  */
399  mpsStatus (*feval)( mpsClientContext* context, const char* url, int nlhs, mpsArray *plhs[], int nrhs, const mpsArray *prhs[] );
400 
401  /**
402  MPS_CLIENT_1_1 version provides support for request execution using HTTPS protocol for secure client-server communication
403  */
404 #if MPS_MAX_VER >= MPS_CLIENT_1_1
405 
406  /** Set client certificate file in PEM format. */
407  void (*setClientCertFile) (mpsClientConfig* config, const char* certFile);
408 
409  /** Get client certificate file */
410  const char* (*getClientCertFile) (const mpsClientConfig* config);
411 
412  /** Set private key file in PEM format */
413  void (*setPrivateKeyFile) (mpsClientConfig* config, const char* pkFile);
414 
415  /** Get the private key file */
416  const char* (*getPrivateKeyFile) (const mpsClientConfig* config);
417 
418  /** Set password for private key file */
419  void (*setPrivateKeyPasswd) (mpsClientConfig* config, const char* passwd);
420 
421  /** Get password for private key file */
422  const char* (*getPrivateKeyPasswd) (const mpsClientConfig* config);
423 
424  /** Set file Certificate Authority file in PEM format */
425  void (*setCAFile) (mpsClientConfig* config, const char* caFile);
426 
427  /** Get Certificate Authority file */
428  const char* (*getCAFile) (const mpsClientConfig* config);
429 
430  /** Set the revocation list file */
431  void (*setRevocationListFile) (mpsClientConfig* config, const char* crlFile);
432 
433  /** Get the revocation list file */
434  const char* (*getRevocationListFile) (const mpsClientConfig* config);
435 
436  /** Setting this flag to true will verify the hostname in thr url against the common name in the certificate */
437  void (*setVerifyHost) (mpsClientConfig* config, mpsLogical verifyHost);
438 
439  /** Get the host verification flag value */
441 
442  /** Setting this flag to false will not peform the authentication of server certificate. Doing so will
443  make the connection insecure and can be prone to man-in-the-middle attack
444  */
445  void (*setVerifyPeer) (mpsClientConfig* config, mpsLogical verifyPeer);
446 
447  /** Get the peer verification flag value */
449 
450 #endif
451 
453 
454 /** Set up the programming environment for MATLAB Production Server client based on
455  version 1.0.
456  This global initialization should be done just once in the program. Invoking
457  it multiple times will return the pointer to the same underlying API struct.
458  @return A pointer to the MATLAB Production Server client API struct.
459 */
461 
462 /** Set up the programming environment for MATLAB Production Server client based
463  on the version number provided by the user. This function can only be used to
464  access the versions above 1.0. To use version 1.0, please use <c>mpsInitialize()</c>
465  function.
466  This global initialization should be done just once in the program. Invoking
467  it multiple times will return the pointer to the same underlying API struct.
468  @return A pointer to the MATLAB Production Server client API struct corresponding
469  to the version provided.
470 */
472 
473 /** Perform global clean up of resources consumed by MATLAB Production Server client environment.
474  This should be done just once in the application.
475  Invoking it multiple times will have no effect.
476 */
478 
479 /** Returns the error message representing the failure in global initialization
480  that sets up the programming environment for MATLAB Production Server client.
481 */
483 
484 /** Determine whether <c>mpsArray</c> represents data as double-precision, floating-point numbers.
485  @param mlArr Pointer to an <c>mpsArray</c>
486  @return True if the array stores its data as double-precision, floating-point numbers, and false otherwise.
487 */
489 
490 /** Determine whether <c>mpsArray</c> represents data as single-precision, floating-point numbers.
491  @param mlArr Pointer to an <c>mpsArray</c>
492  @return True if the array stores its data as single-precision, floating-point numbers, and false otherwise.
493 */
495 
496 /** Determine whether <c>mpsArray</c> contains an imaginary part.
497  @param mlArr Pointer to an <c>mpsArray</c>
498  @return True if the array contains an imaginary part, and false otherwise.
499 */
501 
502 /** Determine whether <c>mpsArray</c> contains numeric data.
503  @param mlArr Pointer to an <c>mpsArray</c>
504  @return True if the array contains numeric data, and false otherwise.
505 */
507 
508 /** Determine whether <c>mpsArray</c> represents data as signed 64-bit integers.
509  @param mlArr Pointer to an <c>mpsArray</c>
510  @return True if the array represents data as signed 64-bit integers, and false otherwise.
511 */
513 
514 /** Determine whether <c>mpsArray</c> represents data as unsigned 64-bit integers.
515  @param mlArr Pointer to an <c>mpsArray</c>
516  @return True if the array represents data as unsigned 64-bit integers, and false otherwise.
517 */
519 
520 /** Determine whether <c>mpsArray</c> represents data as signed 32-bit integers.
521  @param mlArr Pointer to an <c>mpsArray</c>
522  @return True if the array represents data as signed 32-bit integers, and false otherwise.
523 */
525 
526 /** Determine whether <c>mpsArray</c> represents data as unsigned 32-bit integers.
527  @param mlArr Pointer to an <c>mpsArray</c>
528  @return True if the array represents data as unsigned 32-bit integers, and false otherwise.
529 */
531 
532 /** Determine whether <c>mpsArray</c> represents data as signed 16-bit integers.
533  @param mlArr Pointer to an <c>mpsArray</c>
534  @return True if the array represents data as signed 16-bit integers, and false otherwise.
535 */
537 
538 /** Determine whether <c>mpsArray</c> represents data as unsigned 16-bit integers.
539  @param mlArr Pointer to an <c>mpsArray</c>
540  @return True if the array represents data as unsigned 16-bit integers, and false otherwise.
541 */
543 
544 /** Determine whether <c>mpsArray</c> represents data as signed 8-bit integers.
545  @param mlArr Pointer to an <c>mpsArray</c>
546  @return True if the array represents data as signed 8-bit integers, and false otherwise.
547 */
549 
550 /** Determine whether <c>mpsArray</c> represents data as unsigned 8-bit integers.
551  @param mlArr Pointer to an <c>mpsArray</c>
552  @return True if the array represents data as unsigned 8-bit integers, and false otherwise.
553 */
555 
556 /** Determine whether <c>mpsArray</c> represents a string array.
557  @param mlArr Pointer to an <c>mpsArray</c>
558  @return True if the array has the class <c>mpsCHAR_CLASS</c>, and false otherwise.
559 */
561 
562 /** Determine whether <c>mpsArray</c> represents data as <c>mpsLogical</c>.
563  @param mlArr Pointer to an <c>mpsArray</c>
564  @return True if the array represents data as <c>mpsLogical</c>, and false otherwise.
565 */
567 
568 /** Determine whether MATLAB treats the scalar data in the <c>mpsArray</c> as logical or numerical.
569  @param mlArr Pointer to an <c>mpsArray</c>
570  @return True if the array represents data as <c>mpsLogical</c> and has 1-by-1 dimensions, and false otherwise.
571 */
573 
574 /** Determine whether scalar array is true.
575  @param mlArr Pointer to an <c>mpsArray</c>
576  @return True if the value of the array's logical, scalar element is true, and false otherwise.
577 */
579 
580 /** Determine whether input is structure array.
581  @param mlArr Pointer to an <c>mpsArray</c>
582  @return True if the array represents data as <c>mpsStruct</c>, and false otherwise.
583 */
585 
586 /** Determine whether input is cell array.
587  @param mlArr Pointer to an <c>mpsArray</c>
588  @return True if the array has the class <c>mxCELL_CLASS</c>, and false otherwise.
589 */
591 
592 /** Determine whether array is member of specified class.
593  @param mlArr Pointer to an <c>mpsArray</c>
594  @param classname Array category you are testing. You can specify any one of the following predefined constants:
595  Value of <c>classname</c> | Corresponding Class
596  --------------------------| ---------------------
597  `cell` | `mpsCELL_CLASS`
598  `char` | `mpsCHAR_CLASS`
599  `double` | `mpsDOUBLE_CLASS`
600  `int8` | `mpsINT8_CLASS`
601  `int16` | `mpsINT16_CLASS`
602  `int32` | `mpsINT32_CLASS`
603  `int64` | `mpsINT64_CLASS`
604  `logical` | `mpsLOGICAL_CLASS`
605  `single` | `mpsSINGLE_CLASS`
606  `struct` | `mpsSTRUCT_CLASS`
607  `uint8` | `mpsUINT8_CLASS`
608  `uint16` | `mpsUINT16_CLASS`
609  `uint32` | `mpsUINT32_CLASS`
610  `uint64` | `mpsUINT64_CLASS`
611  `<class_name>` | `<class_id>`
612 
613  In the table, `<class_name>` represents the name of a specific MATLAB custom object. You can also specify one of your own class names.
614  @return True if the array has the class <c>classname</c>, and false otherwise.
615 */
616 MPSCLIENT_PUBLISHED_API_EXTERN_C bool mpsIsClass(const mpsArray* mlArr, const char* classname);
617 
618 /** Determine whether array is empty.
619  @param mlArr Pointer to an <c>mpsArray</c>
620  @return True if the array has no data, and false otherwise.
621 */
623 
624 /** Determine whether array is sparse.
625  @param mlArr Pointer to an <c>mpsArray</c>
626  @return True if the array is sparse, and false otherwise.
627 */
629 
630 /** Create a two-dimensional double-precision floating-point array.
631  @param m Number of rows.
632  @param n Number of columns.
633  @param complexFlag If the array is to contain imaginary data, set to <c>mpsCOMPLEX</c>.
634  Otherwise, set to <c>mpsREAL</c>.
635  @return Pointer to the created array.
636 */
638 
639 /** Create a scalar double-precision floating-point array.
640  @param value Value to which you want to initialize the array.
641  @return Pointer to the created array.
642 */
644 
645 /** Create a two-dimensional numeric array.
646  @param m Number of rows.
647  @param n Number of columns.
648  @param classid Identifier for the class of the array, which determines the way the numerical data is represented in memory.
649  @param complexFlag If the array is to contain imaginary data, set to <c>mpsCOMPLEX</c>.
650  Otherwise, set to <c>mpsREAL</c>.
651  @return Pointer to the created array.
652 */
654 
655 /** Create a two-dimensional numeric array.
656  @param ndim Number of dimensions. If you specify a value that is less than 2, the number of
657  dimensions is automatically set to 2.
658  @param dims Dimensions array. Each element in the dimensions array contains the size of the array in that dimension.
659  @param classid Identifier for the class of the array, which determines the way the numerical data is represented in memory.
660  @param complexFlag If the array is to contain imaginary data, set to <c>mpsCOMPLEX</c>.
661  Otherwise, set to <c>mpsREAL</c>.
662  @return Pointer to the created array.
663 */
665  mpsClassID classid, mpsComplexity complexFlag);
666 
667 /** Create a string array.
668  @param str String that is to serve as the initial data.
669  @return Pointer to the created array.
670 */
672 
673 /** Create a two-dimensional string array.
674  @param rows Number of rows in the created array. The value you specify is the number of strings in <c>str</c>.
675  @param str Array of strings containing at least <c>rows</c> strings.
676  @return Pointer to the created array.
677 */
679 
680 /** Create a N-dimensional string array.
681  @param ndim Number of dimensions. If you specify a value that is less than 2, the number of
682  dimensions is automatically set to 2.
683  @param dims Dimensions array. Each element in the dimensions array contains the size of the array in that dimension.
684  @return Pointer to the created array.
685 */
687 
688 /** Create a scalar logical array.
689  @param value Logical value to which you want to initialize the array.
690  @return Pointer to the created array.
691 */
693 
694 /** Create a two-dimensional logical array.
695  @param m Number of rows.
696  @param n Number of columns.
697  @return Pointer to the created array.
698 */
700 
701 /** Create a N-dimensional logical array.
702  @param ndim Number of dimensions. If you specify a value that is less than 2, the number of
703  dimensions is automatically set to 2.
704  @param dims Dimensions array. Each element in the dimensions array contains the size of the array in that dimension.
705  @return Pointer to the created array.
706 */
708 
709 /** Create a two-dimensional struct array.
710  @param m Number of rows.
711  @param n Number of columns.
712  @param nfields Number of fields in each element.
713  @param fieldnames List of field names.
714  @return Pointer to the created array.
715 */
716 MPSCLIENT_PUBLISHED_API_EXTERN_C mpsArray* mpsCreateStructMatrix(mpsSize m, mpsSize n, int nfields, const char **fieldnames);
717 
718 /** Create a N-dimensional struct array.
719  @param ndim Number of dimensions. If you specify a value that is less than 2, the number of
720  dimensions is automatically set to 2.
721  @param dims Dimensions array. Each element in the dimensions array contains the size of the array in that dimension.
722  @param nfields Number of fields in each element.
723  @param fieldnames List of field names.
724  @return Pointer to the created array.
725 */
726 MPSCLIENT_PUBLISHED_API_EXTERN_C mpsArray* mpsCreateStructArray(mpsSize ndim, const mpsSize *dims, int nfields, const char **fieldnames);
727 
728 /** Create a two-dimensional cell array.
729  @param m Number of rows.
730  @param n Number of columns.
731  @return Pointer to the created array.
732 */
734 
735 /** Create a N-dimensional cell array.
736  @param ndim Number of dimensions. If you specify a value that is less than 2, the number of
737  dimensions is automatically set to 2.
738  @param dims Dimensions array. Each element in the dimensions array contains the size of the array in that dimension.
739  @return Pointer to the created array.
740 */
742 
743 /** Create a two-dimensional sparse array.
744  @param m Number of rows.
745  @param n Number of columns.
746  @param nzmax Number of elements to allocate to hold the <c>pr</c>, <c>ir</c>, and, if
747  <c>complexFlag</c> is <c>mpsCOMPLEX</c>), <c>pi</c> arrays. Set the value to be greater than
748  or equal to the number of non-zero elements you plan to put into the array, but make sure that
749  <c>nzmax</c> is less than or equal to <c>m*n</c>.
750  @param complexFlag If the array is to contain imaginary data, set to <c>mpsCOMPLEX</c>.
751  Otherwise, set to <c>mpsREAL</c>.
752  @return Pointer to the created array.
753 */
755 
756 /** Create a two-dimensional sparse array.
757  @param m Number of rows.
758  @param n Number of columns.
759  @param nzmax Number of elements to allocate to hold the data. Set the value to be greater than
760  or equal to the number of non-zero elements you plan to put into the array, but make sure that
761  <c>nzmax</c> is less than or equal to <c>m*n</c>.
762  @return Pointer to the created array.
763 */
765 
766 /** Deallocate the memory occupied by an array.
767  <c>mpsDestroyArray</c> not only deallocates the memory occupied by the array's characteristics
768  fields, but also deallocates all the array's associated data arrays, such as <c>pr</c> and
769  <c>pi</c> for complex arrays, <c>ir</c> and <c>jc</c> for sparse arrays, fields of structure
770  arrays, and cells of cell arrays. Do __not__ call <c>mpsDestroyArray</c> on an array you are
771  returning it in a left side argument.
772  @param mlArr Array to destroy
773 */
775 
776 /** Make a deep copy of input <c>mpsArray</c>.
777  @param mlArr Pointer to an <c>mpsArray</c> to be duplicated
778  @return Duplicate copy of input <c>mpsArray</c>
779 */
781 
782 /** Deallocate heap space using the MATLAB memory management facility.
783  @param data Pointer to the beginning of any memory parcel allocated by MATLAB.
784 */
786 
787 /** Determine the number of dimensions in an array.
788  @param mlArr Pointer to an <c>mpsArray</c>
789  @return Number of dimensions in the array.
790 */
792 
793 /** Determine the number of bytes in each data element of an array.
794  @param mlArr Pointer to an <c>mpsArray</c>
795  @return Number of bytes required to store one element of the specified array.
796 */
798 
799 /** Determine how many elements are in each dimension of an array.
800  @param mlArr Pointer to an <c>mpsArray</c>
801  @return Pointer to the first element in the dimensions array. Each integer in the dimensions
802  array represents the number of elements in a particular dimension. The array is not <c>NULL</c>
803  terminated.
804 */
806 
807 /** Modify number of dimensions and size of each dimension of an array.
808  @param mlArr Pointer to an <c>mpsArray</c>
809  @param dims Dimensions array. Each element in the dimensions array contains the size of the array in that dimension.
810  @param ndim Number of dimensions.
811  @return <c>0</c> on success, and <c>1</c> on failure.
812 */
814 
815 /** Determine how many elements are in the array.
816  @param mlArr Pointer to an <c>mpsArray</c>
817  @return Number of elements in the array.
818 */
820 
821 /** Determine how many elements there are between the beginning of an array and a given element.
822  Arrays in MATLAB are stored column-major, so accessing the elements of an `mpsArray` using
823  standard C indexing will produce a transposed array. This function accepts row-major
824  dimension subscripts and calculate the proper column-major index to the the desired value.
825  @param mlArr Pointer to an <c>mpsArray</c>.
826  @param nsubs Number of elements in the subs array.
827  @param subs Array of integers. Each value in the array specifies that dimension's subscript.
828  @return Number of elements, or _index_, between the start of the array and the specified
829  subscript. This is the linear index equivalent of the subscripts calculated as if the array
830  were stored column major as they are in MATLAB.
831 */
833 
834 /** Determine the first dimension of an array.
835  @param mlArr Pointer to an <c>mpsArray</c>.
836  @return First dimension of the array.
837 */
839 
840 /** Set the first dimension of an array.
841  @param mlArr Pointer to an <c>mpsArray</c>.
842  @param m First dimension of the array.
843 */
845 
846 /** Determine the number of columns in an array.
847  @param mlArr Pointer to an <c>mpsArray</c>.
848  @return Number of columns in the array.
849 */
851 
852 /** Set the number of columns in an array.
853  @param mlArr Pointer to an <c>mpsArray</c>.
854  @param n Number of columns in the array.
855 */
857 
858 /** Determine the value of the first real element of an array.
859  @param mlArr Pointer to an <c>mpsArray</c>.
860  @return Pointer to the value of the first real element of the array.
861 */
863 
864 /** Access the real data in an array of doubles.
865  @param mlArr Pointer to an <c>mpsArray</c> of doubles.
866  @return Pointer to the first element of the real data.
867 */
869 
870 /** Access the imaginary data in an array of doubles.
871  @param mlArr Pointer to an <c>mpsArray</c> of doubles.
872  @return Pointer to the imaginary data elements of the array.
873 */
875 
876 /** Access the real numeric data in an array.
877  @param mlArr Pointer to an <c>mpsArray</c>.
878  @return Pointer to the real data elements of the array.
879 */
881 
882 /** Access the imaginary data in an array.
883  @param mlArr Pointer to an <c>mpsArray</c>.
884  @return Pointer to the imaginary data elements of the array.
885 */
887 
888 /** Access the data in a character array.
889  @param mlArr Pointer to an <c>mpsArray</c>.
890  @return Pointer to the imaginary data elements of the array.
891 */
893 
894 /** Copy the character data of a string array into a C-style string.
895  @param mlArr Pointer to an <c>mpsArray</c> having the <c>mpsCHAR_CLASS</c> class.
896  @param str Starting location for the string. <c>mpsGetString</c> writes the character data
897  into <c>str</c> and then terminates the string with a <c>NULL</c> character.
898  @param len Size, in bytes, of destination buffer pointed to by <c>str</c>.
899  @return <c>0</c> on success or if <c>strlen == 0</c>, and <c>1</c> on failure.
900 */
901 MPSCLIENT_PUBLISHED_API_EXTERN_C int mpsGetString(const mpsArray* mlArr, char* str, mpsSize len);
902 
903 /** Copy the character data of a string array into a C-style string.
904  @param mlArr Pointer to an <c>mpsArray</c> having the <c>mpsCHAR_CLASS</c> class.
905  @return <c>NULL</c> terminated string.
906 */
908 
909 /** Determine the class of an array.
910  @param mlArr Pointer to an <c>mpsArray</c>.
911  @return Numeric identifier of the class of the array.
912 */
914 
915 /** Determine the class of an array.
916  @param mlArr Pointer to an <c>mpsArray</c>.
917  @return String identifier of the class of the array.
918 */
920 
921 /** Access the first logical element in an array.
922  @param mlArr Pointer to an <c>mpsArray</c>.
923  @return Pointer to the first logical element in the array.
924 */
926 
927 /** Access the value held in the specified element of the specified field of an array of struct.
928  @param mlArr Pointer to an <c>mpsArray</c> of struct.
929  @param index Index of the desired element.
930  @param fieldname Name of the field whose value you want to extract.
931  @return Pointer to the <c>mpsArray</c> in the specified field at the specified <c>fieldname</c>.
932 */
933 MPSCLIENT_PUBLISHED_API_EXTERN_C mpsArray *mpsGetField(const mpsArray *mlArr, mpsIndex index, const char *fieldname);
934 
935 /** Set the value held in the specified element of the specified field of an array of struct.
936  @param mlArr Pointer to an <c>mpsArray</c> of struct.
937  @param index Index of the desired element.
938  @param fieldname Name of a field in the struct. The field **must** exist.
939  @param pvalue Pointer to an <c>mpsArray</c> containing the data you want to assign to <c>fieldname</c>.
940 */
941 MPSCLIENT_PUBLISHED_API_EXTERN_C void mpsSetField(mpsArray *mlArr, mpsIndex index, const char *fieldname, mpsArray *pvalue);
942 
943 /** Determine the number of fields in an array of struct.
944  @param mlArr Pointer to an <c>mpsArray</c> of struct.
945  @return Number of fields.
946 */
948 
949 /** Determine the number of a field in an array of struct given the field name.
950  @param mlArr Pointer to an <c>mpsArray</c> of struct.
951  @param fieldname Name of a field in the struct.
952  @return Field number of the specified field.
953 */
954 MPSCLIENT_PUBLISHED_API_EXTERN_C int mpsGetFieldNumber(const mpsArray *mlArr, const char *fieldname);
955 
956 /** Determine the name of a field in an array of struct given the field number.
957  @param mlArr Pointer to an <c>mpsArray</c> of struct.
958  @param fieldnumber Number of a field in the struct.
959  @return Pointer to the name of the specified field.
960 */
961 MPSCLIENT_PUBLISHED_API_EXTERN_C const char *mpsGetFieldNameByNumber(const mpsArray *mlArr, int fieldnumber);
962 
963 /** Access the value held in the specified field number at the indexed element of an array.
964  @param mlArr Pointer to an <c>mpsArray</c> of struct.
965  @param index Index of the desired element.
966  @param fieldnumber Number of a field in the struct.
967  @return Pointer to the <c>mpsArray</c> in the specified field for the desired element.
968 */
969 MPSCLIENT_PUBLISHED_API_EXTERN_C mpsArray *mpsGetFieldByNumber(const mpsArray *mlArr, mpsIndex index, int fieldnumber);
970 
971 /** Set the value held in the specified field number at the indexed element of an array.
972  @param mlArr Pointer to an <c>mpsArray</c> of struct.
973  @param index Index of the desired element.
974  @param fieldnumber Number of a field in the struct.
975  @param pvalue Pointer to the <c>mpsArray</c> containing the data to set.
976 */
977 MPSCLIENT_PUBLISHED_API_EXTERN_C void mpsSetFieldByNumber(mpsArray *mlArr, mpsIndex index, int fieldnumber, mpsArray *pvalue);
978 
979 /** Add a field to an array of struct.
980  @param mlArr Pointer to an <c>mpsArray</c> of struct.
981  @param fieldname Name of the field to add.
982  @return Field number on success, or <c>-1</c> if inputs are invalid or an out-of-memory condition occurs.
983 */
984 MPSCLIENT_PUBLISHED_API_EXTERN_C int mpsAddField(mpsArray *mlArr, const char *fieldname);
985 
986 /** Delete a field from an array of struct.
987  @param mlArr Pointer to an <c>mpsArray</c> of struct.
988  @param fieldnumber Number of the field to delete.
989 */
990 MPSCLIENT_PUBLISHED_API_EXTERN_C void mpsRemoveField(mpsArray *mlArr, int fieldnumber);
991 
992 /** Access the contents of a cell array at a specified index.
993  @param mlArr Pointer to an <c>mpsArray</c> cell array.
994  @param index Number of elements in the cell array between the first element and the desired one.
995  @return Pointer to the data in specified cell of the array.
996 */
998 
999 /** Set the contents of a cell array at a specified index.
1000  @param mlArr Pointer to an <c>mpsArray</c> cell array.
1001  @param index Number of elements in the cell array between the first element and the desired one.
1002  @param value Pointer to new value for the cell. You can put an <c>mpsArray</c> of any type into a
1003  cell. You can even put another cell <c>mpsArray</c> into a cell.
1004 */
1006 
1007 /** Determine the number of non-zero elements in a sparse array.
1008  @param mlArr Pointer to a sparse <c>mpsArray</c>.
1009  @return Number of elements allocated to hold non-zero entries in the specified sparse array.
1010 */
1012 
1013 /** Set the maximum number of non-zero elements in a sparse array.
1014  @param mlArr Pointer to a sparse <c>mpsArray</c>.
1015  @param nzmax Number of elements allocated to hold the arrays pointed to by <c>ir</c>, <c>pr</c>,
1016  and <c>pi</c>. Set <c>nzmax</c> greater than or equal to the number of non-zero elements in the array,
1017  but set it to be less than or equal to the number of rows times the number of columns. If you
1018  specify a value of <c>0</c>, the value of nzmax is automatically set to <c>1</c>.
1019 */
1021 
1022 /** Determine the starting address of the <c>ir</c> array in a sparse array.
1023  @param mlArr Pointer to a sparse <c>mpsArray</c>.
1024  @return Pointer to the first element in the <c>ir</c> array.
1025 */
1027 
1028 /** Determine the starting address of the <c>jc</c> array in a sparse array.
1029  @param mlArr Pointer to a sparse <c>mpsArray</c>.
1030  @return Pointer to the first element in the <c>jc</c> array.
1031 */
1033 
1034 #endif