ANSI INCITS ISO IEC 14365-1996 Information technology - MHS-based electronic messaging C language interfaces - Binding for Application Program Interface (API) (Adopted by INCITS).pdf

1、INTERNATIONAL STANDARD ISO/IEC 14365 First edition 1996-06-o 1 Information technology - MHS-based electronic messaging C language interfaces - Binding for Application Program Interface (API) Technologies de /information - Interfaces de langage C en messagerie klectronique ba Telephone: +1202 371-010

2、1; FAX: +1202 728-9614. Introduction vii INTERNATIONAL STANDARD OISO/IEC ISO/IEC 14365:1996(E) 1 Information technology-MHS-based 2 electronic messaging C language 3 interfaces-Binding for Application Program 4 Interface (API) Section 1: General 6 7 This International Standard defines an ISO/IEC 998

3、9 I C language binding to 8 the language-independent API defined in ISO/IEC 14361 I3l.l It is intended to 9 support application portability at the source-code level and to be used by applica- 10 tion developers, system implementors, test method writers, and users. 11 12 13 14 15 1.2 Normative Refere

4、nces 16 The following standards contain provisions which, through reference in this text, 17 constitute provisions of this International Standard. At the time of publication, 18 the editions indicated were valid. All standards are subject to revision, and parties 19 to agreements based on this Inter

5、national Standard are encouraged to investigate 20 the possibility of applying the most recent editions of the standards indicated 1.1 Scope The interface is oriented towards the needs of gateways and applications that require full access to the features of the protocols. NOTE: There are industry-st

6、andard and proprietary AFIs that can be used by simple applications that only require the main features of the protocols. 21 1) The numbers in curly brackets correspond to those of the normative references in 1.2. 1.2 Normative References 1 22 Iso/IEC 14365:1996(E) OISO/IEC below. Members of IEC and

7、 IS0 maintain registers of currently valid Interna- tional Standards. 23 24 25 26 27 28 29 30 31 32 33 34 ISO/IEC 9989: 19902), Programming languages-C. ISO/IEC 14360: 1996, Information technology-Open Systems Interconnec- tion (OSI) abstract data manipulation-Application Program Interface (API) Lan

8、guage independent. ISO/IEC 14361: 1996, I f n ormation technology-MHS-based electronic messaging-Application Program Interface (API) Language independent. ISOIIEC 14363: 1996, Information technology-Test methods for measuring conformance to MHS-based electronic messaging-Application Program Interfac

9、e (API Language independent. ISOIIEC 14367: 1996, Information technology-Test methods for measuring conformance to MHS-based electronic messaging C language interfaces-Binding for Application Program Interface (API). 35 1.3 Conformance 36 1.3.1 Implementation Conformance 37 1.3.1.1 Requirements 38 A

10、 conforming implementation for this International Standard shall be a conform- 39 ing implementation, as defined in ISO/IEC 14361 3, for the programming 40 language binding specification that is contained in this International Standard. 41 1.3.1.2 Documentation 42 43 44 45 46 47 48 49 50 A conforman

11、ce document shall be available for an implementation claiming confor- mance to this International Standard. It shall satisfy the requirements that are defined in ISO/IEC 14361 3) for a conformance document for a programming language binding specification. The phrases “shall document” or “shall be do

12、cumented” in this International Stan- dard mean that documentation of the feature shall appear in the conformance document, unless the system documentation is explicitly mentioned. The system documentation should also contain the information found in the confor- mance document. 51 2) ISO/IEC documen

13、ts can be obtained from the IS0 Central Secretariat, 1 Rue de VarembB, Case 52 Postale 56, CH-1211, Gen 10 OM-boolean activated; 11 1 MH-feature; 12 13 14 15 16 3.2.2 Interval 17 18 19 20 21 Section 3: Message Handling Interfaces 3.1 Introduction This section defines the C language binding to the me

14、ssage handling interfaces in ISOAEC 14361 (3). 3.2.1.2 Description This single datatype, used for negotiating the features of a session, corresponds to both the mh-feature_listJype and mh-activated-list-type datatypes defined in ISO/IEC 14361 3. 3.2.2.1 C Declaration typedef OM-uint32 MH-interval; 3

15、2.2.2 Description This datatype, used to denote an interval of time in milliseconds, corresponds to the mh-feature-type datatype defined in ISO/lEC 14361 (3). 3.2 Datatypes 9 ISO/DX! 14365:1996(E) OISOKIEC 3.2.3 Object Count 22 3.2.3.1 C Declaration 23 typedef OM-uint32 MH-object-count; 24 3.2.3.2

16、Description 25 This datatype, an integer that denotes a number of objects, corresponds to the mh- 26 object-count-type datatype defined in ISOLIEC 14361 (31. 27 3.2.4 Sequence Number 28 3.2.4.1 C Declaration 29 typedef OM-uint32 MH-sequence-number; 30 3.2.4.2 Description 31 This datatype, used to de

17、note the sequence number of an object in a retrieval 32 queue, corresponds to the mh-sequence-number-type datatype defined in ISO/IEC 33 14361 (3). 34 3.3 Access Functions 35 The C language functions defined in this section correspond directly to the 36 language-independent operations of ISOLIEC 143

18、61 (3). They are therefore not 37 described further in this International Standard, except where there is some 38 feature of the C language binding that is not present in the language-independent 39 specification. 40 41 42 OM-return-code 43 ma-cancel-submission ( 44 OM_private-object 45 OM-object 46

19、 1; 47 48 This function, used to cancel a submitted message with the deferred delivery 49 option, corresponds to the ma-cancel-submission operation defined in ISOAEC 50 14361 3. 3.3.1 Cancel Submission 3.3.1.1 C Declaration session, mts-identifier 3.3.1.2 Description 10 3 Message Handling Interfaces

20、 OISOLIEC ISO/IEX 14366:1996(E) 51 OMPOINTERINVALIDl 52 3.3.2 Close 53 3.3.2.1 C Declaration 54 OM-return-code 55 ma-close ( 56 OMqrivate-object 57 1; 58 3.3.2.2 Description 59 This function, used to terminate an MA session between the client and the service, 60 corresponds to the ma-close operation

21、 defined in ISO/IEC 1436113). 61 3.3.2.3 Errors 62 OMPOINTER.JNVALIDl 63 3.3.3 Finish Delivery 64 3.3.3.1 C Declaration 65 OM-return-code 66 ma-finish-delivery ( 67 OMqrivate-object 68 OM-object 69 OM-object 70 1; 71 3.3.3.2 Description 72 This function, used to conclude the delivery in progress in

22、a session, corresponds to 73 the ma-finish-delivery operation defined in ISO/IEC 14361 13). 74 75 76 77 78 79 80 3.3.1.3 Errors session session, delivery-confirmations, non-delivery-reports 3.3.3.3 Arguments delivery-confirmations When the argument delivery-confirmations is omitted, its absence is s

23、ignaled by the null pointer. non-delivery-reports When the argument non-delivery-reports is omitted, its absence is signaled by the null pointer. 3.3 Access Functions 11 ISO/IEC 14365:1996(E) OISO/IEC 81 OMPOINTERINVALID 82 83 84 OM-return-code 85 ma-finish-retrieval ( 86 OMqrivate-object 87 OM-bool

24、ean 88 ); 89 3.3.4.2 Description 90 This function, used to conclude the retrieval in progress in a session, corresponds to 91 the ma-finish-retrieval operation defined in ISO/IEC 14361 13). 92 3.3.4.3 Errors 93 OMPOINTERINVALIDl 94 95 96 OM-return-code 97 ma-open ( 98 OM_public-object 99 OM-string 1

25、00 MI-I-feature 101 OMqrivate-object 102 OM-workspace 103 1 ; 104 3.3.5.2 Description 105 This function, used to establish an MA session between the client and the service, 106 corresponds to the ma-open operation defined in ISO/IEC 143613). 107 108 feature-list The sequence of MH session, *number 3

26、3.6.2 Description 123 This function, used to determine the number of messages and reports in the delivery or retrieval queue, corresponds to the ma-size operation defined in ISO/IEC 14361 (3). 124 125 126 127 3.3.6.3 Errors 128 OMPOINTERINVALIDl 129 3.3.7 Start Delivery 130 3.3.7.1 C Declaration 13

27、1 OM-return-code 132 ma-start-delivery ( 133 OMqrivate-object 134 OMqrivate-object 135 1; session, *object 136 3.3.7.2 Description 137 This function, used to begin the delivery of a message or a report to one or more of 138 the users associated with a session, corresponds to the ma-start-delivery op

28、eration 139 defined in ISO/IEC 1436113). 3.3.7.3 Errors OM-POINTER-INVALID 140 141 3.3 Access Functions 13 ISO/IEC 14365:1996(E) OISO/IEC 3.3.8 Start Retrieval 3.3.8.1 C Declaration 142 143 OM-return-code 144 ma-start-retrieval ( 145 OMqrivate-object 146 MI-I-sequence-number 147 MH-sequence-number 1

29、48 OMgrivate-object 149 1; session, minimum.gequence-number, *selected-sequence-number, *object 3.3.8.2 Description 150 151 This function, used to begin the retrieval of a message or a report, corresponds to 152 the ma-start-retrieval operation defined in ISO/IEC 14361 (3). 3.3.8.3 Errors 153 OM-POI

30、NTER-INVALID 154 3.3.9 Submit 155 3.3.9.1 C Declaration 156 157 OM-return-code 158 ma-submit ( 159 OMqrivate-object 160 OM-object 161 OMgrivate-object 162 1; session, communique, *submission-results 3.3.9.2 Description 163 164 This function, used to submit a communique, corresponds to the ma-submit

31、opera- 165 tion defined in ISO/IEC 14361(3. 3.3.9.3 Errors 166 OM-POINTERJNVALID 167 3.3.10 Wait 168 3.3.10.1 C Declaration 169 170 OM-return-code 171 ma-wait ( 172 OMgrivate-object 173 MI-I-interval session, interval, 14 3 Message Handling Interfaces OISO/IEC ISO/IEC 14365:1996(E) 174 175 176 3.3.1

32、0.2 Description 177 This function, used to indicate when a message or a report is available for delivery 178 or retrieval, or when a period of time elapses, whichever occurs first, corresponds to 179 the ma-wait operation defined in ISO/IEC 14361 (31. 180 3.3.10.3 Arguments 181 minimum-sequence-numb

33、er 182 For delivery queues, the minimum-sequence-number argument it 183 is present but is ignored by the service. 184 3.3.10.4 Errors 185 OMPOINTERJNVALIDI 186 3.4 Transfer Functions 187 The C language functions defined in this section correspond directly to the 188 language-independent operations o

34、f ISO/IEC 14361 (3). They are therefore not 189 described further in this International Standard, except where there is some 190 feature of the C language binding that is not present in the language-independent 191 specification. 192 193 3.4.1.1 C Declaration 194 OM-return-code 195 mt-close ( 196 OM

35、private-object 197 1; 198 3.4.1.2 Description 199 This function, used to terminate an MT session between the client and the service, 200 corresponds to the mt-close operation defined in ISO/IEC 1436113). 201 3.4.1.3 Errors 202 ); MI-I-sequence-number OM-boolean minimum-sequence2nunber, *available 3

36、4.1 Close session 3.4 Transfer Functions 15 ISO/IEC 14365:1996(E) OISO/IEC 3.4.2 Finish Transfer In 3.4.2.1 C Declaration 203 204 OM-return-code 205 mt-finish-transfer-in ( 206 OMqrivate-object 207 OMqrivate-object 208 OM-boolean 209 1; session, object, remove 3.4.2.2 Description 210 This function,

37、 used to conclude one or all of the transfers in progress in a session, corresponds to the mt-finish-transfer-in operation defined in ISO/IEC 14361 (3). 211 212 213 3.4.2.3 Arguments object The All argument in ISO/IEC 14361 (3) is also signaled by the - object argument in the C interface. The All ar

38、gument is true if, and only if, the object argument is the null pointer. 214 215 216 217 3.4.2.4 Errors 218 3.4.3 Open 219 220 3.4.3.1 C Declaration 221 OM-return-code 222 mt-open ( 223 OM-string 224 OM-string 225 MI-I-feature 226 OMgrivate-object 227 OM-workspace 228 1; client-name, client-instance

39、name, feature-list, *session, *workspace 229 3.4.3.2 Description 230 This function, used to establish an MT session between the client and the service, 231 corresponds to the mt-open operation defined in ISOLIEC 14361131. 232 3.4.3.3 Arguments 233 feature-list The sequence of MHfeature structures i

40、s terminated by an object 234 identifier with no components (a length of zero and any value of 235 the data pointer). 16 3 Message Handling Interfaces OISOLIEC ISODEC 14365:1996(E) 237 238 3.4.3.4 Errors 239 OMPOINTERJVVALIDl 240 241 3.4.4.1 C Declaration 242 OM-return-code 243 mt-size ( 244 OMqriva

41、te-object 245 MI-I-object-count 246 1; 247 3.4.4.2 Description 248 This function, used to determine the number of communiques or reports in the 249 input queue, corresponds to the mt-size operation defined in ISO/IEC 14361 (3). 250 3.4.4.3 Errors 251 OMPOINTERINVALIDl 252 253 3.4.5.1 C Declaration 2

42、54 OM-return-code 255 mt-start-transfer-in ( 256 OM_private-object 257 OMqrivate-object 258 OM-string 259 1; 260 261 This function, used to begin the transfer in of a communique or a report, 262 corresponds to the mt-start-transfer-in operation defined in ISO/IEC 14361 (3). The language-independent

43、result parameter activated is com- bined with feature-list in the C interface as a single array of structures of type MHfeature. 3.4.4 Size session, *number 3.4.5 Start Transfer In session, *object, *identifier 3.4.5.2 Description 3.4 Transfer Functions 17 ISO/IEC 14365:1996(E) OISOLIEC 263 264 265

44、266 267 268 269 3.4.5.4 Errors 270 OM-POINTER-INVALID 271 3.4.6 Transfer Out 272 3.4.6.1 C Declaration 273 OM-return-code 274 mt-transfer-out ( 275 OMqrivate-object 276 OM-object 277 1; 278 3.4.6.2 Description 279 This function, used to add a communique or a report to the output queue, 280 correspon

45、ds to the mt-transfer-out operation defined in ISO/IEC 14361 (3). 281 3.4.6.3 Errors 282 OM-POINTER-INVALID 283 284 3.4.7.1 C Declaration 285 OM-return-code 286 mt-wait ( 287 OMqrivate-object 288 MI-I-interval 289 OM-boolean 290 1; 291 292 293 294 3.4.5.3 Arguments identifier The client provides, by

46、 means of the pointer in the identifier argu- ment, the storage into which the service is to place the returned identifier and the actual length of the returned identifier. That space must be sufficient to accommodate the longest allowed identifier. It is also the responsibility of the client to de-

47、allocate the storage when the identifier is no longer useful. session, object 3.4.7 wait session, interval, *available 3.4.7.2 Description This function, used to return when a communique or a report is available for transfer in, or when a period of time elapses (whichever occurs first), corresponds

48、to the mt-wait operation defined in ISO/IEC 14361 3. 18 3 Message Handling Interfaces 295 In addition to the return codes defined in ISO/IEC 14361 131, the following return 296 code is defined for the C language binding. It can be returned by each of the func- 297 tions defined in this section: 298

49、 OM-POINTER-INVALID. An invalid pointer was supplied as a function 299 argument or as the receptacle for a function result. 300 3.6 Header File 301 The implementation shall provide a header file, called cxmh.h, for use by applica- 302 tions programs. It shall contain definitions of all types, values, and macros that 303 this section of the International Standard requires. The symbols specified in this 304 section shall be the only symbols the service makes visible to the client, other than 305 those symbols associated with the packag