This file is indexed.

/usr/include/OpenIPMI/ipmi_sol.h is in libopenipmi-dev 2.0.22-1.1ubuntu2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
/*
 * ipmi_sol.h
 *
 * IPMI Serial-over-LAN Client Code
 *
 * Author: Cyclades Australia Pty. Ltd.
 *         Darius Davis <darius.davis@cyclades.com>
 *
 * Copyright 2005 Cyclades Australia Pty. Ltd.
 *
 *  This program is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public License
 *  as published by the Free Software Foundation; either version 2 of
 *  the License, or (at your option) any later version.
 *
 *
 *  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
 *  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 *  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 *  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
 *  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 *  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
 *  TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 *  USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this program; if not, write to the Free
 *  Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

/**
 * @file include/OpenIPMI/ipmi_sol.h
 * Interface for OpenIPMI Serial-over-LAN support.
 * 
 * In keeping with the design of OpenIPMI, the SoL (Serial over LAN) API is
 * designed for asynchronous, event-based use.  Once you have an ipmi_con_t
 * representing a LAN-based connection to a BMC, you can pass that structure
 * to ipmi_sol_create to create an ipmi_sol_conn_t structure which will
 * represent the SoL connection.
 *
 * At this point, one registers callbacks for events as required (i.e. data
 * received, break received, connection state change), configures the bit rate,
 * authentication and encryption, then calls ipmi_sol_open.
 *
 * The client software can then call ipmi_write(...) to send data to the BMC,
 * and will receive data through the callback(s) that have been registered.
 *
 * When the connection is no longer required, the client is to call
 * ipmi_sol_close, which closes the SoL connection.  ipmi_sol_free is then
 * used to dispose of the connection structure if it is no longer required.
 *
 * SoL supports a number of nonvolatile configuration parameters.  These
 * parameters are supported through a series of functions to set the
 * default bit rate, required levels of permission, authentication and
 * encryption, as well as flow-control parameters (Character Accumulate
 * Interval and Character Send Threshold) and retry parameters (Retry
 * Count and Retry Interval).  These functions are a part of the separate
 * ipmi_sol_config interface. (YET TO BE IMPLEMENTED)
 *
 *
 * Reference:
 *  [1] "IPMI - Intelligent Platform Management Interface Specification
 *	Second Generation v2.0", Document Revision 1.0, February 12, 2004,
 *	with June 1, 2004 Markup.  Accessed at:
 *    ftp://download.intel.com/design/servers/ipmi/IPMIv2_0rev1_0markup.pdf
 *
 * For configuration of SoL parameters, refer to:
 *	include/OpenIPMI/include/ipmi_sol.h
 */

#ifndef _IPMI_SOL_H
#define _IPMI_SOL_H

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Queue identification constants for ipmi_sol_flush(...).
 */
#define IPMI_SOL_BMC_TRANSMIT_QUEUE                0x01
#define IPMI_SOL_BMC_RECEIVE_QUEUE                 0x02
#define IPMI_SOL_MANAGEMENT_CONSOLE_TRANSMIT_QUEUE 0x04
#define IPMI_SOL_MANAGEMENT_CONSOLE_RECEIVE_QUEUE  0x08

#define IPMI_SOL_BMC_QUEUES (IPMI_SOL_BMC_TRANSMIT_QUEUE \
			     | IPMI_SOL_BMC_RECEIVE_QUEUE)

#define IPMI_SOL_MANAGEMENT_CONSOLE_QUEUES \
	(IPMI_SOL_MANAGEMENT_CONSOLE_TRANSMIT_QUEUE \
	 | IPMI_SOL_MANAGEMENT_CONSOLE_RECEIVE_QUEUE)

#define IPMI_SOL_ALL_QUEUES (IPMI_SOL_BMC_QUEUES \
			     | IPMI_SOL_MANAGEMENT_CONSOLE_QUEUES)


/**
 * Bit rate constants (almost the same as baud rates)
 */
#define IPMI_SOL_BIT_RATE_DEFAULT		0x00
#define IPMI_SOL_BIT_RATE_9600			0x06
#define IPMI_SOL_BIT_RATE_19200			0x07
#define IPMI_SOL_BIT_RATE_38400			0x08
#define IPMI_SOL_BIT_RATE_57600			0x09
#define IPMI_SOL_BIT_RATE_115200		0x0a


/**
 * The possible states of a SoL connection object.
 */
typedef enum
{
    /* The connection is closed; no data transfer is possible. */
    ipmi_sol_state_closed,

    /* The connection is currently starting up; no data transfer yet. */
    ipmi_sol_state_connecting,

    /* The connection is up and operational. */
    ipmi_sol_state_connected,

    /* The connection is up, but the BMC has reported Character
       Transfer Unavailable.  This means the BMC is flow-controlling
       us. */
    ipmi_sol_state_connected_ctu,

    /* The connection is going down.  No data transfer. */
    ipmi_sol_state_closing
} ipmi_sol_state;


/**
 * Values to specify serial alert behavior while SoL is activated.
 */
typedef enum
{
    ipmi_sol_serial_alerts_fail = 0,
    ipmi_sol_serial_alerts_deferred = 1,
    ipmi_sol_serial_alerts_succeed = 2
} ipmi_sol_serial_alert_behavior;


/**
 * Opaque data structure representing an IPMI SoL connection.
 */
typedef struct ipmi_sol_conn_s ipmi_sol_conn_t;


/**
 * IPMI SoL callbacks
 */

/**
 * This callback is used to indicate a change in the state of a connection.
 *
 * @param [in] conn	The IPMI SoL connection.
 * @param [in] state	Identifies the state of the SoL connection.
 * @param [in] error	A value indicating the circumstances causing the change.
 *	- zero: The state change was due to a request from the client library.
 *	- IPMI_SOL_DISCONNECTED: The state change was due to the loss of a
 *		connection to the managed system.
 *	- IPMI_SOL_NOT_AVAILABLE: This indicates that the management console
 *		responded inappropriately while the library was trying to
 *		connect to SoL on the BMC, so the connection attempt has been
 *		abandoned.  Only given on a transition from ipmi_sol_state_connecting
 *		to ipmi_sol_state_closed.
 *	- IPMI_RMCPP_INVALID_PAYLOAD_TYPE: The remote indicates that it can not
 *		support a compatible version of the SoL payload.  This error
 *		will only be given on a transition from ipmi_sol_state_connecting
 *		to ipmi_sol_state_closed.
 *	- IPMI_SOL_DEACTIVATED: The change is because SoL has been deactivated on the
 *		managed system.
 *	- Another error code from IPMI or the Operating System.
 * @param [in] cb_data	The user-defined value provided when registering
 *			for the callback.
 */
typedef void (*ipmi_sol_connection_state_cb)(ipmi_sol_conn_t *conn,
					     ipmi_sol_state  state,
					     int             error,
					     void            *cb_data);


/**
 * This callback is called for each write request or control-line status
 * request.
 *
 * @param [in] conn	The IPMI SoL connection.
 * @param [in] error	The result of the transmit operation:
 *	- zero: The request has been ACKed and was successful.
 *	- IPMI_SOL_DISCONNECTED: A packet has failed to be delivered
 *		after the configured number of retries.  The connection is lost
 *		and the request is discarded.
 *	- IPMI_SOL_CHARACTER_TRANSFER_UNAVAIL: The managed system is powered down
 *		or is otherwise unable to accept a character transfer.
 *	- IPMI_SOL_DEACTIVATED: The BMC has lost the serial connection
 *		due to intervention at the managed system.
 *	- IPMI_SOL_UNCONFIRMABLE_OPERATION: The request has been transmitted to
 *		the managed system, but the managed system is not expected
 *		acknowledge receipt.
 *	- Another error code (i.e. ENOMEM) to indicate another type of failure.
 * @param [in] cb_data	The user-defined value provided when registering
 *			for the callback.
 */
typedef void (*ipmi_sol_transmit_complete_cb)(ipmi_sol_conn_t *conn,
					      int             error,
					      void            *cb_data);


/**
 * This callback is called asynchronously when characters have been received
 * from the remote.
 *
 * This callback is registered using
 * ipmi_register_data_received_callback.  The recipient of this
 * callback has the opportunity to refuse (NACK) the data by returning
 * a nonzero value; conversely, it should return zero if the packet
 * contents have been accepted.  Note that if a NACK is returned, the
 * BMC will hold packets until ipmi_sol_release_nack() is called or
 * a flush is done.
 *
 * @param [in] conn	The IPMI SoL connection.
 * @param [in] buf	A pointer to the character data.
 * @param [in] count	The number of characters in the buffer.
 * @param [in] cb_data	The user-defined value provided when registering
 *			for the callback.
 * @return	Zero if the data is accepted, nonzero if the data should be
 *		NACKed.
 */
typedef int (*ipmi_sol_data_received_cb)(ipmi_sol_conn_t *conn,
					 const void      *buf,
					 size_t          count,
					 void            *cb_data);


/**
 * This callback will be called upon the successful completion of a flush 
 * operation, or upon the determination of an error condition during the
 * flush operation.
 *
 * @param [in] conn	The IPMI SoL connection.
 * @param [in] error	The result of the flush operation:
 *	- zero: The flush operation completed successfully.
 *	- IPMI_SOL_DISCONNECTED: A packet has failed to be delivered
 *		after the configured number of retries.  The connection is lost.
 *	- IPMI_SOL_DEACTIVATED: The BMC has lost the serial connection
 *		due to intervention at the managed system.
 *	- IPMI_SOL_UNCONFIRMABLE_OPERATION: The data has been transmitted to the
 *		managed system, the managed system can not be expected confirm
 *		receipt.
 * @param [in] queue_selectors_flushed	A bit mask indicating which queues
 *			were successfully flushed.
 * @param [in] cb_data	The user-defined value provided when registering
 *			for the callback.
 */
typedef void (*ipmi_sol_flush_complete_cb)(ipmi_sol_conn_t *conn,
					   int             error,
					   int         queue_selectors_flushed,
					   void            *cb_data);


/**
 * This callback is called asynchronously when the remote indicates it has 
 * detected a serial "break".
 *
 * This callback is registered using ipmi_register_break_detected_callback.
 *
 * @param [in] conn	The IPMI SoL connection.
 * @param [in] cb_data	The user-defined value provided when registering
 *			for the callback.
 */
typedef void (*ipmi_sol_break_detected_cb)(ipmi_sol_conn_t *conn,
					   void            *cb_data);


/**
 * This callback is called asynchronously when the remote BMC indicates that
 * it has encountered a transmitter overrun.  Some incoming data may have
 * been lost.
 *
 * This callback is registered using ipmi_register_bmc_transmit_overrun_callback.
 *
 * @param [in] conn	The IPMI SoL connection.
 * @param [in] cb_data	The user-defined value provided when registering
 *			for the callback.
 */
typedef void (*ipmi_sol_bmc_transmit_overrun_cb)(ipmi_sol_conn_t *conn,
						 void            *cb_data);


/**
 * Constructs a handle for managing an SoL session.
 *
 * This function does NOT communicate with the BMC or activate the SoL payload.
 *
 * @param [in] ipmi	the existing IPMI over LAN session.
 * @param [out] sol_conn	the address into which to store the allocated
 *				IPMI SoL connection structure.
 * @return	zero on success, or ENOMEM if memory allocation fails.
 */
int ipmi_sol_create(ipmi_con_t      *ipmi,
		    ipmi_sol_conn_t **sol_conn);



/**************************************************************************
 ** IPMI SoL connection configuration
 **/


/**
 * Register for callbacks.  For each of the following eight functions, the 
 * parameters are as follows:
 *
 * @param [in] conn	The IPMI SoL connection.
 * @param [in] cb	The callback to register.
 * @param [in] cb_data	The user-defined data to pass to the callback.
 * @return Zero on success, or a nonzero error code.
 */
int ipmi_sol_register_connection_state_callback(ipmi_sol_conn_t *conn,
					       ipmi_sol_connection_state_cb cb,
						void            *cb_data);
int ipmi_sol_deregister_connection_state_callback(ipmi_sol_conn_t *conn,
					       ipmi_sol_connection_state_cb cb,
						  void *cb_data);

int ipmi_sol_register_data_received_callback(ipmi_sol_conn_t *conn,
					     ipmi_sol_data_received_cb cb,
					     void            *cb_data);
int ipmi_sol_deregister_data_received_callback(ipmi_sol_conn_t *conn,
					       ipmi_sol_data_received_cb cb,
					       void            *cb_data);

int ipmi_sol_register_break_detected_callback(ipmi_sol_conn_t *conn,
					      ipmi_sol_break_detected_cb cb,
					      void            *cb_data);
int ipmi_sol_deregister_break_detected_callback(ipmi_sol_conn_t *conn,
						ipmi_sol_break_detected_cb cb,
						void            *cb_data);

int ipmi_sol_register_bmc_transmit_overrun_callback(ipmi_sol_conn_t *conn,
					   ipmi_sol_bmc_transmit_overrun_cb cb,
						    void            *cb_data);
int ipmi_sol_deregister_bmc_transmit_overrun_callback(ipmi_sol_conn_t *conn,
					   ipmi_sol_bmc_transmit_overrun_cb cb,
						      void           *cb_data);


/**
 * Set the timeout to wait for an ACK from the BMC (for packets that expect an
 * ACK).
 *
 * @param [in] conn	The IPMI SoL connection to configure.
 * @param [in] timeout_usec	The timeout, in microseconds.
 */
void ipmi_sol_set_ACK_timeout(ipmi_sol_conn_t *conn, int timeout_usec);

/**
 * Get the timeout to wait for an ACK from the BMC (for packets that expect an
 * ACK).
 *
 * @param [in] conn	The IPMI SoL connection to configure.
 *
 * @return	The timeout
 */
int ipmi_sol_get_ACK_timeout(ipmi_sol_conn_t *conn);


/**
 * Set the number of retries that we make before declaring a packet "lost".
 *
 * @param [in] conn	The IPMI SoL connection to configure.
 * @param [in] retries	The number of retries before a packet is declared lost.
 */
void ipmi_sol_set_ACK_retries(ipmi_sol_conn_t *conn, int retries);

/**
 * Get the number of retries that we make before declaring a packet "lost".
 *
 * @param [in] conn	The IPMI SoL connection to configure.
 *
 * @return	The number of retries
 */
int ipmi_sol_get_ACK_retries(ipmi_sol_conn_t *conn);

/**
 * Configure the authentication to use for the SoL packets.
 *
 * @param [in] conn	The IPMI SoL connection to configure.
 * @param [in] use_authentication	Nonzero to use authentication for the
 * 					SoL packets.
 * @return	Zero on success, otherwise an error code.
 */
int ipmi_sol_set_use_authentication(ipmi_sol_conn_t *conn,
				    int             use_authentication);

/**
 * Query the authentication configuration for the SoL packets.
 *
 * @param [in] conn	The IPMI SoL connection to query.
 * @return	Nonzero iff the connection will attempt to use authentication
 *		for SoL packets.
 */
int ipmi_sol_get_use_authentication(ipmi_sol_conn_t *conn);


/**
 * Configure the encryption to use for the SoL packets.
 * 
 * @param [in] conn	The IPMI SoL connection to configure.
 * @param [in] use_encryption	Nonzero to use encryption for the
 *				SoL packets.
 * @return	Zero on success, otherwise an error code.
 */
int ipmi_sol_set_use_encryption(ipmi_sol_conn_t *conn, int use_encryption);

/**
 * Query the encryption configuration for the SoL packets.
 *
 * @param [in] conn	The IPMI SoL connection to query.
 * @return	Nonzero iff the connection will attempt to use encryption
 *		for SoL packets.
 */
int ipmi_sol_get_use_encryption(ipmi_sol_conn_t *conn);


/**
 * Configure the shared serial alert behavior for the SoL connection.
 * 
 * @param [in] conn	The IPMI SoL connection to configure.
 * @param [in] behavior	A constant identifying the desired shared serial alert
 *			behavior during the SoL connection.
 * @return	Zero on success, otherwise an error code.
 */
int ipmi_sol_set_shared_serial_alert_behavior(ipmi_sol_conn_t *conn,
				      ipmi_sol_serial_alert_behavior behavior);

/**
 * Query the shared serial alerts behavior configuration for the SoL connection.
 *
 * @param [in] conn	The IPMI SoL connection to query.
 * @return	A value identifying the shared serial alert behavior that
 *		will be in force during the connection.
 */
ipmi_sol_serial_alert_behavior ipmi_sol_get_shared_serial_alert_behavior
						      (ipmi_sol_conn_t *conn);


/**
 * Configure the CTS, DCD and DSR deassert-on-connect behavior to use for
 * the SoL connection.
 * 
 * @param [in] conn	The IPMI SoL connection to configure.
 * @param [in] assert	Nonzero to deassert the handshaking signals at the
 * 			start of the SoL connection.
 * @return	Zero on success, otherwise an error code.
 */
int ipmi_sol_set_deassert_CTS_DCD_DSR_on_connect(ipmi_sol_conn_t *conn,
						 int             assert);

/**
 * Query the CTS, DCD and DSR deassert-on-connect configuration for the 
 * SoL connection.
 *
 * @param [in] conn	The IPMI SoL connection to query.
 * @return	Nonzero iff the connection will deassert CTS, DCD and DSR upon
 *		connection.
 */
int ipmi_sol_get_deassert_CTS_DCD_DSR_on_connect(ipmi_sol_conn_t *conn);


/**
 * Configure the bit rate to use on connection.
 *
 * @param [in] conn	The IPMI SoL connection to configure.
 * @param [in] rate	The bit rate constant (IPMI_SOL_BIT_RATE_xxxxx)
 * @return	Zero on success, otherwise an error code.
 */
int ipmi_sol_set_bit_rate(ipmi_sol_conn_t *conn, unsigned char rate);


/**
 * Query the bit rate to be used upon connection.
 *
 * @param [in] conn	The IPMI SoL connection to query.
 * @return		The bit rate that will be used (IPMI_SOL_BIT_RATE_xxxxx)
 */
unsigned char ipmi_sol_get_bit_rate(ipmi_sol_conn_t *conn);


/**
 * Opens the SoL connection using the previously set nonvolatile and
 * volatile parameters.
 *
 * This contacts the BMC and checks that we share a compatible revision of
 * SoL, and that this connection has the privileges to activate SoL.  If this
 * function returns an ERROR, the callback will never be called.  If it returns
 * no error, the callback WILL be called, indicating whether the connection was
 * successful or not.
 *
 * @param [in] conn	The IPMI SoL connection handle from ipmi_sol_create.
 * @param [in] cb	The callback to use to indicate success or failure
 *			of the operation.  This is only used if ipmi_sol_open
 *			returns zero.
 * @param [in] cb_data	User-defined data to pass to the callback.
 *
 * @return	Zero on success.
 *		EINVAL if this handle is already connected.
 *		A nonzero IPMI error code on other failure.
 */
int ipmi_sol_open(ipmi_sol_conn_t *conn);


/**
 * Requests the closure of the SoL session.
 *
 * Closing the SoL session also restores the baseboard serial mux to its
 * initial state.
 * 
 * @param [in] conn	The IPMI SoL connection to close.
 * @param [in] force	Nonzero if the connection should be forced to close.
 *			Forcing the connection to close will be a synchronous
 *			operation.  All outstanding transmits will be cancelled
 *			and the transmit_complete callbacks will be called
 *			indicating that the transmit failed.  The connection_
 *			state callback will also be called before this function
 *			returns.
 * @return	Zero on success.
 *		EINVAL if this handle was already closing or closed.  If the
 * 			handle is closing, consider using ipmi_sol_force_close
 *			to hurry it along.
 *		A nonzero error code on other failure.
 */
int ipmi_sol_close(ipmi_sol_conn_t *conn);


/**
 * Forces the closure of the SoL session.
 *
 * The BMC is notified that the connection will should close, but no attempt
 * is made to wait for a response from the BMC.  Otherwise, this function does
 * purely local cleanup of outstanding transmit callbacks and connection-
 * oriented memory allocations.
 * 
 * @param [in] conn	The IPMI SoL connection to close.
 * @return	Zero on success.
 *		EINVAL if this handle was already closed.
 *		A nonzero IPMI error code on other failure.
 */
int ipmi_sol_force_close(ipmi_sol_conn_t *conn);


/**
 * Frees the memory used by the SoL connection structure.  No callbacks will
 * occur after this function is called.  The connection will be forced closed
 * if it was still open when the function was called.
 * 
 * @param [in] conn	The IPMI SoL connection to release.
 * @return	Zero on success, or a nonzero IPMI error code on failure.
 */
int ipmi_sol_free(ipmi_sol_conn_t *conn);



/******************************************************************************
 ** IPMI SoL write operations (and sundry operations that cause a transmit)
 **/
 
/**
 * Send a sequence of bytes to the remote.
 *
 * This function (like all the others!) will either return an ERROR and
 * never call the callback, or will return success and then WILL call
 * the callback, indicating an error later if necessary. The callback is
 * an indication that the BMC has ACKed *all* of the bytes in this request.
 * There is no guarantee that the packet will not be fragmented or
 * coalesced in transmission.
 *
 * @param [in] conn	The IPMI SoL connection over which to transmit.
 * @param [in] buf	A pointer to the data to transmit.
 * @param [in] count	The nonzero number of bytes to send.
 * @param [in] cb	The callback to call when the transmission is complete.
 *			This callback will only be called if this function call
 *			returns zero.
 * @param [in] cb_data	User-defined data to pass to the callback.
 * @return	Zero on success
 *		EINVAL	if a request is made to transmit zero bytes
 *		or a nonzero IPMI error code on failure.
 */
int ipmi_sol_write(ipmi_sol_conn_t *conn,
		   const void      *buf,
		   int             count,
		   ipmi_sol_transmit_complete_cb cb,
		   void            *cb_data);


/**
 * Release a NACK
 *
 * This function will release a NACK returned by the receive routine.
 * For every NACK a receive routine returns, this must be called to
 * reactivate receiving packets from the BMC.
 *
 * @param [in] conn	The IPMI SoL connection over which to transmit.
 * @return	Zero on success
 *		EINVAL	No NACK is pending.
 */
int ipmi_sol_release_nack(ipmi_sol_conn_t *conn);


/**
 * Request that the BMC send a serial "break" to the managed system.
 *
 * @param [in] conn	The IPMI SoL connection over which to transmit.
 * @param [in] cb	The callback to call when the transmission is complete.
 *			This callback will only be called if this function call
 *			returns zero.
 * @param [in] cb_data	User-defined data to pass to the callback.
 * @return	Zero on success, or a nonzero IPMI error code on failure.
 *		Callback is likely to receive IPMI_SOL_UNCONFIRMABLE_OPERATION
 *		because the BMC will not bother to acknowledge the receipt of
 *		this request unless it is sent at the same time as a block of
 * 		data.
 */
int ipmi_sol_send_break(ipmi_sol_conn_t *conn,
			ipmi_sol_transmit_complete_cb cb,
			void            *cb_data);


/**
 * Controls CTS at the BMC, to request that the system attached to the BMC
 * ceases transmitting characters. No guarantee is given that the BMC and/or
 * baseboard will honour this request. Further buffered characters might still
 * be received after CTS is deasserted.
 *
 * Choosing to "deassert" CTS here really puts CTS under the control of the BMC
 * for its own flow control.
 * 
 * @param [in] conn	The IPMI SoL connection.
 * @param [in] assertable	Nonzero puts the CTS signal in the control of
 *				the BMC.  Zero prevents the BMC from asserting
 *				the CTS signal.
 * @param [in] cb	The callback to call when the operation is complete.
 *			This callback will only be called if this function call
 *			returns zero.
 * @param [in] cb_data	User-defined data to pass to the callback.
 * @return	Zero on success, or a nonzero IPMI error code on failure.
 *		Callback is likely to receive IPMI_SOL_UNCONFIRMABLE_OPERATION
 *		because the BMC will not bother to acknowledge the receipt of
 *		this request unless it is sent at the same time as a block of
 * 		data.
 */
int ipmi_sol_set_CTS_assertable(ipmi_sol_conn_t *conn,
				int             asserted,
				ipmi_sol_transmit_complete_cb cb,
				void            *cb_data);


/**
 * Asserts DCD and DSR at the BMC, as if we've answered the phone line.
 * 
 * @param [in] conn	The IPMI SoL connection.
 * @param [in] asserted	Nonzero if DCD and DSR should be asserted.
 * @param [in] cb	The callback to call when the operation is complete.
 *			This callback will only be called if this function call
 *			returns zero.
 * @param [in] cb_data	User-defined data to pass to the callback.
 * @return	Zero on success, or a nonzero IPMI error code on failure.
 *		Callback is likely to receive IPMI_SOL_UNCONFIRMABLE_OPERATION
 *		because the BMC will not bother to acknowledge the receipt of
 *		this request unless it is sent at the same time as a block of
 * 		data.
 */
int ipmi_sol_set_DCD_DSR_asserted(ipmi_sol_conn_t *conn,
				  int             asserted,
				  ipmi_sol_transmit_complete_cb cb,
				  void            *cb_data);


/**
 * Asserts RI, as if the phone line is ringing.
 *
 * The stated aim of this operation is to allow use of the Wake-on-Ring feature
 * to power-up and gain the attention of a system.
 * 
 * @param [in] conn	The IPMI SoL connection.
 * @param [in] asserted	Nonzero if RI should be asserted by the BMC.
 * @param [in] cb	The callback to call when the operation is complete.
 *			This callback will only be called if this function call
 *			returns zero.
 * @param [in] cb_data	User-defined data to pass to the callback.
 * @return	Zero on success, or a nonzero IPMI error code on failure.
 *		Callback is likely to receive IPMI_SOL_UNCONFIRMABLE_OPERATION
 *		because the BMC will not bother to acknowledge the receipt of
 *		this request unless it is sent at the same time as a block of
 * 		data.
 */
int ipmi_sol_set_RI_asserted(ipmi_sol_conn_t *conn,
			     int             asserted,
			     ipmi_sol_transmit_complete_cb cb,
			     void            *cb_data);


/**
 * Requests a flush of the transmit queue(s) identified by queue_selector.
 * 
 * If no error is returned, the callback will be called in a synchronous
 * manner if the flush does not involve the BMC, asynchronous if it does.
 *
 * @param [in] conn	The IPMI SoL connection.
 * @param [in] queue_selectors	 Identifies the queues to flush.  This is
 *				specified as a bitwise-OR of the following:
 *
 *			- IPMI_SOL_BMC_TRANSMIT_QUEUE
 *			- IPMI_SOL_BMC_RECEIVE_QUEUE
 *			- IPMI_SOL_MANAGEMENT_CONSOLE_TRANSMIT_QUEUE
 *			- IPMI_SOL_MANAGEMENT_CONSOLE_RECEIVE_QUEUE
 *
 *			or use IPMI_SOL_ALL_QUEUES, IPMI_SOL_BMC_QUEUES or
 *			IPMI_SOL_MANAGEMENT_CONSOLE_QUEUES
 *
 * @param [in] cb	The callback to call when the operation is complete.
 *			This callback will only be called if this function call
 *			returns zero.
 * @param [in] cb_data	User-defined data to pass to the callback.
 * @return	Zero on success, or a nonzero IPMI error code on failure.
 *		Callback is likely to receive IPMI_SOL_UNCONFIRMABLE_OPERATION
 *		because the BMC will not bother to acknowledge the receipt of
 *		this request unless it is sent at the same time as a block of
 * 		data.
 */
int ipmi_sol_flush(ipmi_sol_conn_t *conn,
		   int             queue_selectors,
		   ipmi_sol_flush_complete_cb cb,
		   void            *cb_data);

#ifdef __cplusplus
}
#endif

#endif /* _IPMI_SOL_H */