modemu2k.h

Go to the documentation of this file.

#pragma once

#include <poll.h>     /* struct pollfd, used by m2k_get_pollfds()/m2k_step() below */
#include <stddef.h>   /* size_t */

#include "modemu2k_version.h"  /* M2K_VERSION_MAJOR / _MINOR / _PATCH / M2K_VERSION */

#ifndef M2K_API
# if defined(_WIN32)
#  if defined(M2K_BUILDING_DLL)
#   define M2K_API __declspec(dllexport)
#  else
#   define M2K_API __declspec(dllimport)
#  endif
# elif defined(__GNUC__) && __GNUC__ >= 4
#  define M2K_API __attribute__((visibility("default")))
# else
#  define M2K_API
# endif
#endif

/* Deprecation marker. Consumers see a -Wdeprecated-declarations
 * warning at the call site. modemu2k's own build defines
 * M2K_SUPPRESS_DEPRECATED so the in-tree tests that still exercise
 * the deprecated path build clean. */
#if defined(M2K_SUPPRESS_DEPRECATED)
# define M2K_DEPRECATED(msg)
#elif defined(__GNUC__) || defined(__clang__)
# define M2K_DEPRECATED(msg) __attribute__((deprecated(msg)))
#elif defined(_MSC_VER)
# define M2K_DEPRECATED(msg) __declspec(deprecated(msg))
#else
# define M2K_DEPRECATED(msg)
#endif

#ifdef __cplusplus
extern "C" {
#endif

typedef struct m2k_s m2k_t;

M2K_API const char *m2k_version(void);

typedef void (*m2k_log_fn)(const char *msg, void *userdata);

/* Note: new codes are appended; existing values must never be reordered
   so external callers can safely cache numeric values across releases. */
typedef enum {
  M2K_OK = 0,       
  M2K_ERR_NOMEM,    
  M2K_ERR_PTY,      
  M2K_ERR_SOCKET,   
  M2K_ERR_TIMEOUT,  
  M2K_ERR_CANCELED, 
  M2K_ERR_BUG,      
  M2K_ERR_WOULDBLOCK, 
  M2K_ERR_AT,       
} m2k_err_t;

M2K_API m2k_t      *m2k_new(void);

M2K_API void        m2k_free(m2k_t *ctx);

M2K_API void        m2k_set_log_fn(m2k_t *ctx, m2k_log_fn fn, void *userdata);

#define M2K_ERROR_BUFFER_SIZE 256

M2K_API void        m2k_set_error_buffer(m2k_t *ctx, char *buf, size_t size);

M2K_API m2k_err_t   m2k_atcmd(m2k_t *ctx, const char *cmd);

M2K_API M2K_DEPRECATED("use m2k_run() or the step API instead")
m2k_err_t           m2k_dial(m2k_t *ctx, const char *host, const char *port);

M2K_API M2K_DEPRECATED("use m2k_run() or the step API instead")
m2k_err_t           m2k_online(m2k_t *ctx);

M2K_API m2k_err_t   m2k_hangup(m2k_t *ctx);

M2K_API m2k_err_t   m2k_escape(m2k_t *ctx);

M2K_API const char *m2k_strerror(m2k_err_t err);

M2K_API m2k_err_t   m2k_setup_stdin(m2k_t *ctx);

M2K_API m2k_err_t   m2k_setup_pty(m2k_t *ctx, const char **slave_out);

M2K_API m2k_err_t   m2k_setup_comm_program(m2k_t *ctx, const char *cmd);

M2K_API m2k_err_t   m2k_setup_dev(m2k_t *ctx, const char *dev);

M2K_API m2k_err_t   m2k_setup_listen(m2k_t *ctx, const char *port);

M2K_API m2k_err_t   m2k_setup_app_io(m2k_t *ctx);

M2K_API m2k_err_t   m2k_write_from_app(m2k_t *ctx, const void *buf, size_t len,
                               size_t *consumed);

M2K_API m2k_err_t   m2k_read_to_app(m2k_t *ctx, void *buf, size_t max, size_t *len_out);

M2K_API int         m2k_has_pending_output(const m2k_t *ctx);

M2K_API int         m2k_get_listen_fd(const m2k_t *ctx);

M2K_API m2k_err_t   m2k_listen_accept(m2k_t *ctx);

M2K_API m2k_err_t   m2k_run(m2k_t *ctx);

/* ── Steppable event-loop API ───────────────────────────────────────
 *
 * The functions below let a host application integrate modemu2k into
 * its own event loop (poll/epoll/select/etc.) instead of handing the
 * fds to the blocking m2k_run() above.
 *
 * Usage:
 *   while (!m2k_run_done(ctx)) {
 *       struct pollfd fds[M2K_MAX_POLLFDS];   // caller-provided buffer
 *       size_t nfds = M2K_MAX_POLLFDS;
 *       int timeout_ms;
 *       m2k_get_pollfds(ctx, fds, &nfds, &timeout_ms);
 *       // Splice fds into your own pollset, call poll()/epoll_wait().
 *       // On return, write back the .revents the OS reported into the
 *       // corresponding entries of `fds`.
 *       m2k_step(ctx, fds, nfds);
 *   }
 *
 * Dialing (ATD) is non-blocking: m2k_step() transitions the context
 * into an internal DIAL state on ATD, returns control immediately,
 * and resumes the connect() across subsequent m2k_step() calls. The
 * host event loop is not held up by connect(). m2k_get_pollfds()
 * publishes the in-progress socket fd while DIAL is active, so the
 * host pollset stays accurate without special-casing.
 */

#define M2K_MAX_POLLFDS 3

M2K_API m2k_err_t   m2k_get_pollfds(m2k_t *ctx, struct pollfd *fds,
                            size_t *nfds_inout, int *timeout_ms);

M2K_API m2k_err_t   m2k_step(m2k_t *ctx, struct pollfd *fds, size_t nfds);

M2K_API int         m2k_run_done(const m2k_t *ctx);

M2K_API int         m2k_is_online(const m2k_t *ctx);

M2K_API int         m2k_has_carrier(const m2k_t *ctx);

M2K_API void        m2k_set_dtr(m2k_t *ctx, int on);

M2K_API void        m2k_set_rts(m2k_t *ctx, int on);

M2K_API int         m2k_get_dtr(const m2k_t *ctx);

M2K_API int         m2k_get_rts(const m2k_t *ctx);

M2K_API void        m2k_set_force_verbose(m2k_t *ctx, int on);

M2K_API int         m2k_get_force_verbose(const m2k_t *ctx);

#ifdef __cplusplus
}
#endif