libfossil
fsl_sc_popen_state Struct Reference

State for use with the fsl_sc_popen fsl_sc impl. More...

#include "sync.h"

Collaboration diagram for fsl_sc_popen_state:

Data Fields

struct { 
   char *   location 
 Location where the binary was found. More...
   char const *   name 
 The name of the program binary, e.g. More...
} bin
 Info about the binary.
fsl_buffer cmd
 The command line to invoke.
struct { 
   int(*   buildCommandLine )(fsl_sc *ch, fsl_buffer *b,
       fsl_buffer const *bLoginCard) 
 Command arguments initializer. More...
   void(*   cleanup )(fsl_sc_popen_state *st) 
 May be set for subclasses in order to clean up any dynamic state owned by this object in this->impl.state. More...
   int(*   init )(fsl_sc *ch) 
 This optional method gets called as part of the FSL_SC_INIT_INITIAL phase of fsl_sc::init() to give subclasses a way to perform any validation they may need. More...
   void *   state 
 Subclass-specific state. More...
} impl
 State for "subclasses".
struct { 
   void *   allocStamp 
 Internal implementation detail. More...
   char *   tmpfilePrefix 
 A random prefix for temp file names. More...
} misc
 Flag(s).
struct { 
   int   fdStdOut 
 The external process's stdout, i.e. More...
   FILE *   fStdIn 
 The external process's stdin, i.e. More...
   int   pid 
 The external process's PID. More...
} process
 State for/around fsl__popen2().
struct { 
   unsigned   count 
 Number of initiated requests. More...
   char *   filename 
 Filename of this->fp. More...
   FILE *   fp 
 Request payload temp file. More...
} request
 State for the sync request payload.
struct { 
   fsl_buffer   b 
 Response body when this->mode is fsl_sc_popen_e_membuf. More...
   unsigned   count 
 Number of initiated response-reads. More...
   int   fd 
 Response input source when this->mode is fsl_sc_popen_e_fd. More...
   char *   filename 
 Response temp file when this->response.mode is fsl_sc_popen_e_filebuf or fsl_sc_popen_e_fd. More...
   FILE *   fp 
 Response source file when this->mode is fsl_sc_popen_e_filebuf. More...
   enum fsl_sc_popen_e   mode 
 How to read the response. More...
} response
 State for the sync response payload.

Detailed Description

State for use with the fsl_sc_popen fsl_sc impl.

fsl_sc_popen requires that its state member point to an instance of this class.

This type acts as a base implemtation for channels which "shell out" to an external binary to provide the transport layer. e.g. curl can be used for HTTP(S) and fossil(1)'s own "test-http" mechanism can be used this way.

Definition at line 907 of file sync.h.

Field Documentation

◆ allocStamp

void* fsl_sc_popen_state::allocStamp

Internal implementation detail.

Tells fsl_sc_popen's cleanup() impl whether or not to free() this object.

Definition at line 1068 of file sync.h.

◆ b

fsl_buffer fsl_sc_popen_state::b

Response body when this->mode is fsl_sc_popen_e_membuf.

Definition at line 1057 of file sync.h.

◆ [struct]

struct { ... } fsl_sc_popen_state::bin

Info about the binary.

◆ buildCommandLine

int(* fsl_sc_popen_state::buildCommandLine) (fsl_sc *ch, fsl_buffer *b, fsl_buffer const *bLoginCard)

Command arguments initializer.

Must be set by concrete implementations and it gets invoked via fsl_sc::submit(). Implementations must populate b using ((fsl_sc_popen_state*)ch->impl.p)'s state, namely the request.filename and response.filename members, which are names of temporary files which will eventually contain the request payload and response payloads.

Implementations must use fsl_buffer_escape_arg() and friends to append a complete command line to b. They must return 0 on success.

When this is called (early on in the fsl_sc::submit() process):

  • this->bin.location will be set to the command to invoke. It must be prepended to the command line (or may it may be proxied via a separate command known only to the concrete implementation).
  • this->url will be set to the remote fossil URL.
  • this->request.filename is a file which the command is expected to read the fossil sync request body payload from.
  • If this->response.filename is not NULL then it is a file which the command is expected to write the fossil sync response to, minus any transport-layer metadata like HTTP headers. If it is NULL, the process is expected to write to stdout.
  • None of the other this->request and this->response members will be set up.
  • If bLoginCard is not NULL then it will hold the content for a fossil sync login card. Implementations must emit an HTTP header in the form "Cookie: x-f-x-l=XYZ" where XYZ is the URL-encoded content of bLoginCard. For fsl_sc impls which use the FSL_SC_F_REQUEST_HEADERS flag, the library will have populated ch->requestHeaders before this is called, including the login card.

Definition at line 966 of file sync.h.

◆ cleanup

void(* fsl_sc_popen_state::cleanup) (fsl_sc_popen_state *st)

May be set for subclasses in order to clean up any dynamic state owned by this object in this->impl.state.

It will be called early in the fsl_sc::cleanup() step, before st's base class state are cleaned.

Whether or not it must free st is implementation-defined.

Definition at line 977 of file sync.h.

◆ cmd

fsl_buffer fsl_sc_popen_state::cmd

The command line to invoke.

This is intended to be set up by this->impl.buildCommandLine.

Definition at line 1084 of file sync.h.

◆ count

unsigned fsl_sc_popen_state::count

Number of initiated requests.

Number of initiated response-reads.

Definition at line 1024 of file sync.h.

◆ fd

int fsl_sc_popen_state::fd

Response input source when this->mode is fsl_sc_popen_e_fd.

Definition at line 1051 of file sync.h.

◆ fdStdOut

int fsl_sc_popen_state::fdStdOut

The external process's stdout, i.e.

a read-only stream.

Definition at line 1010 of file sync.h.

◆ filename

char* fsl_sc_popen_state::filename

Filename of this->fp.

Response temp file when this->response.mode is fsl_sc_popen_e_filebuf or fsl_sc_popen_e_fd.

Definition at line 1020 of file sync.h.

◆ fp

FILE* fsl_sc_popen_state::fp

Request payload temp file.

Response source file when this->mode is fsl_sc_popen_e_filebuf.

This file is opened in "w+b" mode.

Definition at line 1022 of file sync.h.

◆ fStdIn

FILE* fsl_sc_popen_state::fStdIn

The external process's stdin, i.e.

a write-only stream.

Definition at line 1008 of file sync.h.

◆ [struct]

struct { ... } fsl_sc_popen_state::impl

State for "subclasses".

Not really subclasses, but "concrete implementations" gets unwieldy after a while.

◆ init

int(* fsl_sc_popen_state::init) (fsl_sc *ch)

This optional method gets called as part of the FSL_SC_INIT_INITIAL phase of fsl_sc::init() to give subclasses a way to perform any validation they may need.

It may also perform any one-time initialization it may need to do.

If it returns non-0, channel initialization fails.

Definition at line 921 of file sync.h.

◆ location

char* fsl_sc_popen_state::location

Location where the binary was found.

If NULL, it defaults to a $PATH search of this->bin.name. Clients may set this before use, but (A) it must be allocated using a libfossil API, e.g. fsl_mprintf(), and (B) this memory is owned by this object.

If the client does not set this, the library will search in the $PATH for this->name and assign that value here.

Definition at line 1003 of file sync.h.

◆ [struct]

struct { ... } fsl_sc_popen_state::misc

Flag(s).

◆ mode

enum fsl_sc_popen_e fsl_sc_popen_state::mode

How to read the response.

This should never be set by clients. It's for library-internal experimentation. If it must be set as part of a struct initialization, set it to fsl_sc_popen_e_default.

Definition at line 1037 of file sync.h.

◆ name

char const* fsl_sc_popen_state::name

The name of the program binary, e.g.

"curl". It is expected to be findable via the $PATH.

Definition at line 992 of file sync.h.

◆ pid

int fsl_sc_popen_state::pid

The external process's PID.

Definition at line 1012 of file sync.h.

◆ [struct]

struct { ... } fsl_sc_popen_state::process

State for/around fsl__popen2().

◆ [struct]

struct { ... } fsl_sc_popen_state::request

State for the sync request payload.

◆ [struct]

struct { ... } fsl_sc_popen_state::response

State for the sync response payload.

◆ state

void* fsl_sc_popen_state::state

Subclass-specific state.

Owned by this object's cleanup() method.

Definition at line 983 of file sync.h.

◆ tmpfilePrefix

char* fsl_sc_popen_state::tmpfilePrefix

A random prefix for temp file names.

Memory is owned by this object. All request and response temp files are prefixed with this and get a predictable suffix. We generate a random prefix, rather than a new random name on each call, to simplify grouping of the files for development and debugging purposes.

Definition at line 1077 of file sync.h.


The documentation for this struct was generated from the following file: