sqlcipher/ext/session/sqlite3session.h at sqlite-release · sqlcipher/sqlcipher · GitHub

History

2101 lines (2034 loc) · 92.5 KB

Raw

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

743

744

745

746

747

748

749

750

751

752

753

754

755

756

757

758

759

760

761

762

763

764

765

766

767

768

769

770

771

772

773

774

775

776

777

778

779

780

781

782

783

784

785

786

787

788

789

790

791

792

793

794

795

796

797

798

799

800

801

802

803

804

805

806

807

808

809

810

811

812

813

814

815

816

817

818

819

820

821

822

823

824

825

826

827

828

829

830

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

847

848

849

850

851

852

853

854

855

856

857

858

859

860

861

862

863

864

865

866

867

868

869

870

871

872

873

874

875

876

877

878

879

880

881

882

883

884

885

886

887

888

889

890

891

892

893

894

895

896

897

898

899

900

901

902

903

904

905

906

907

908

909

910

911

912

913

914

915

916

917

918

919

920

921

922

923

924

925

926

927

928

929

930

931

932

933

934

935

936

937

938

939

940

941

942

943

944

945

946

947

948

949

950

951

952

953

954

955

956

957

958

959

960

961

962

963

964

965

966

967

968

969

970

971

972

973

974

975

976

977

978

979

980

981

982

983

984

985

986

987

988

989

990

991

992

993

994

995

996

997

998

999

1000

#if !defined(__SQLITESESSION_H_) && defined(SQLITE_ENABLE_SESSION)

#define __SQLITESESSION_H_ 1

** Make sure we can call this stuff from C++.

#ifdef __cplusplus

extern "C" {

#endif

#include "sqlite3.h"

** CAPI3REF: Session Object Handle

** An instance of this object is a [session] that can be used to

** record changes to a database.

typedef struct sqlite3_session sqlite3_session;

** CAPI3REF: Changeset Iterator Handle

** An instance of this object acts as a cursor for iterating

** over the elements of a [changeset] or [patchset].

typedef struct sqlite3_changeset_iter sqlite3_changeset_iter;

** CAPI3REF: Create A New Session Object

** CONSTRUCTOR: sqlite3_session

** Create a new session object attached to database handle db. If successful,

** a pointer to the new object is written to *ppSession and SQLITE_OK is

** returned. If an error occurs, *ppSession is set to NULL and an SQLite

** error code (e.g. SQLITE_NOMEM) is returned.

** It is possible to create multiple session objects attached to a single

** database handle.

** Session objects created using this function should be deleted using the

** [sqlite3session_delete()] function before the database handle that they

** are attached to is itself closed. If the database handle is closed before

** the session object is deleted, then the results of calling any session

** module function, including [sqlite3session_delete()] on the session object

** are undefined.

** Because the session module uses the [sqlite3_preupdate_hook()] API, it

** is not possible for an application to register a pre-update hook on a

** database handle that has one or more session objects attached. Nor is

** it possible to create a session object attached to a database handle for

** which a pre-update hook is already defined. The results of attempting

** either of these things are undefined.

** The session object will be used to create changesets for tables in

** database zDb, where zDb is either "main", or "temp", or the name of an

** attached database. It is not an error if database zDb is not attached

** to the database when the session object is created.

int sqlite3session_create(

sqlite3 *db, /* Database handle */

const char *zDb, /* Name of db (e.g. "main") */

sqlite3_session **ppSession /* OUT: New session object */

);

** CAPI3REF: Delete A Session Object

** DESTRUCTOR: sqlite3_session

** Delete a session object previously allocated using

** [sqlite3session_create()]. Once a session object has been deleted, the

** results of attempting to use pSession with any other session module

** function are undefined.

** Session objects must be deleted before the database handle to which they

** are attached is closed. Refer to the documentation for

** [sqlite3session_create()] for details.

void sqlite3session_delete(sqlite3_session *pSession);

** CAPI3REF: Configure a Session Object

** METHOD: sqlite3_session

** This method is used to configure a session object after it has been

** created. At present the only valid values for the second parameter are

** [SQLITE_SESSION_OBJCONFIG_SIZE] and [SQLITE_SESSION_OBJCONFIG_ROWID].

int sqlite3session_object_config(sqlite3_session*, int op, void *pArg);

** CAPI3REF: Options for sqlite3session_object_config

** The following values may passed as the the 2nd parameter to

** sqlite3session_object_config().

** <dt>SQLITE_SESSION_OBJCONFIG_SIZE <dd>

** This option is used to set, clear or query the flag that enables

** the [sqlite3session_changeset_size()] API. Because it imposes some

** computational overhead, this API is disabled by default. Argument

** pArg must point to a value of type (int). If the value is initially

** 0, then the sqlite3session_changeset_size() API is disabled. If it

** is greater than 0, then the same API is enabled. Or, if the initial

** value is less than zero, no change is made. In all cases the (int)

** variable is set to 1 if the sqlite3session_changeset_size() API is

** enabled following the current call, or 0 otherwise.

** It is an error (SQLITE_MISUSE) to attempt to modify this setting after

** the first table has been attached to the session object.

** <dt>SQLITE_SESSION_OBJCONFIG_ROWID <dd>

** This option is used to set, clear or query the flag that enables

** collection of data for tables with no explicit PRIMARY KEY.

** Normally, tables with no explicit PRIMARY KEY are simply ignored

** by the sessions module. However, if this flag is set, it behaves

** as if such tables have a column "_rowid_ INTEGER PRIMARY KEY" inserted

** as their leftmost columns.

** It is an error (SQLITE_MISUSE) to attempt to modify this setting after

** the first table has been attached to the session object.

#define SQLITE_SESSION_OBJCONFIG_SIZE 1

#define SQLITE_SESSION_OBJCONFIG_ROWID 2

** CAPI3REF: Enable Or Disable A Session Object

** METHOD: sqlite3_session

** Enable or disable the recording of changes by a session object. When

** enabled, a session object records changes made to the database. When

** disabled - it does not. A newly created session object is enabled.

** Refer to the documentation for [sqlite3session_changeset()] for further

** details regarding how enabling and disabling a session object affects

** the eventual changesets.

** Passing zero to this function disables the session. Passing a value

** greater than zero enables it. Passing a value less than zero is a

** no-op, and may be used to query the current state of the session.

** The return value indicates the final state of the session object: 0 if

** the session is disabled, or 1 if it is enabled.

int sqlite3session_enable(sqlite3_session *pSession, int bEnable);

** CAPI3REF: Set Or Clear the Indirect Change Flag

** METHOD: sqlite3_session

** Each change recorded by a session object is marked as either direct or

** indirect. A change is marked as indirect if either:

** <ul>

** <li> The session object "indirect" flag is set when the change is

** made, or

** <li> The change is made by an SQL trigger or foreign key action

** instead of directly as a result of a users SQL statement.

** </ul>

** If a single row is affected by more than one operation within a session,

** then the change is considered indirect if all operations meet the criteria

** for an indirect change above, or direct otherwise.

** This function is used to set, clear or query the session object indirect

** flag. If the second argument passed to this function is zero, then the

** indirect flag is cleared. If it is greater than zero, the indirect flag

** is set. Passing a value less than zero does not modify the current value

** of the indirect flag, and may be used to query the current state of the

** indirect flag for the specified session object.

** The return value indicates the final state of the indirect flag: 0 if

** it is clear, or 1 if it is set.

int sqlite3session_indirect(sqlite3_session *pSession, int bIndirect);

** CAPI3REF: Attach A Table To A Session Object

** METHOD: sqlite3_session

** If argument zTab is not NULL, then it is the name of a table to attach

** to the session object passed as the first argument. All subsequent changes

** made to the table while the session object is enabled will be recorded. See

** documentation for [sqlite3session_changeset()] for further details.

** Or, if argument zTab is NULL, then changes are recorded for all tables

** in the database. If additional tables are added to the database (by

** executing "CREATE TABLE" statements) after this call is made, changes for

** the new tables are also recorded.

** Changes can only be recorded for tables that have a PRIMARY KEY explicitly

** defined as part of their CREATE TABLE statement. It does not matter if the

** PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid alias) or not. The PRIMARY

** KEY may consist of a single column, or may be a composite key.

** It is not an error if the named table does not exist in the database. Nor

** is it an error if the named table does not have a PRIMARY KEY. However,

** no changes will be recorded in either of these scenarios.

** Changes are not recorded for individual rows that have NULL values stored

** in one or more of their PRIMARY KEY columns.

** SQLITE_OK is returned if the call completes without error. Or, if an error

** occurs, an SQLite error code (e.g. SQLITE_NOMEM) is returned.

** <h3>Special sqlite_stat1 Handling</h3>

** As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception to

** some of the rules above. In SQLite, the schema of sqlite_stat1 is:

** <pre>

**   CREATE TABLE sqlite_stat1(tbl,idx,stat)

** </pre>

** Even though sqlite_stat1 does not have a PRIMARY KEY, changes are

** recorded for it as if the PRIMARY KEY is (tbl,idx). Additionally, changes

** are recorded for rows for which (idx IS NULL) is true. However, for such

** rows a zero-length blob (SQL value X'') is stored in the changeset or

** patchset instead of a NULL value. This allows such changesets to be

** manipulated by legacy implementations of sqlite3changeset_invert(),

** concat() and similar.

** The sqlite3changeset_apply() function automatically converts the

** zero-length blob back to a NULL value when updating the sqlite_stat1

** table. However, if the application calls sqlite3changeset_new(),

** sqlite3changeset_old() or sqlite3changeset_conflict on a changeset

** iterator directly (including on a changeset iterator passed to a

** conflict-handler callback) then the X'' value is returned. The application

** must translate X'' to NULL itself if required.

** Legacy (older than 3.22.0) versions of the sessions module cannot capture

** changes made to the sqlite_stat1 table. Legacy versions of the

** sqlite3changeset_apply() function silently ignore any modifications to the

** sqlite_stat1 table that are part of a changeset or patchset.

int sqlite3session_attach(

sqlite3_session *pSession, /* Session object */

const char *zTab /* Table name */

);

** CAPI3REF: Set a table filter on a Session Object.

** METHOD: sqlite3_session

** The second argument (xFilter) is the "filter callback". For changes to rows

** in tables that are not attached to the Session object, the filter is called

** to determine whether changes to the table's rows should be tracked or not.

** If xFilter returns 0, changes are not tracked. Note that once a table is

** attached, xFilter will not be called again.

void sqlite3session_table_filter(

sqlite3_session *pSession, /* Session object */

int(*xFilter)(

void *pCtx, /* Copy of third arg to _filter_table() */

const char *zTab /* Table name */

void *pCtx /* First argument passed to xFilter */

);

** CAPI3REF: Generate A Changeset From A Session Object

** METHOD: sqlite3_session

** Obtain a changeset containing changes to the tables attached to the

** session object passed as the first argument. If successful,

** set *ppChangeset to point to a buffer containing the changeset

** and *pnChangeset to the size of the changeset in bytes before returning

** SQLITE_OK. If an error occurs, set both *ppChangeset and *pnChangeset to

** zero and return an SQLite error code.

** A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes,

** each representing a change to a single row of an attached table. An INSERT

** change contains the values of each field of a new database row. A DELETE

** contains the original values of each field of a deleted database row. An

** UPDATE change contains the original values of each field of an updated

** database row along with the updated values for each updated non-primary-key

** column. It is not possible for an UPDATE change to represent a change that

** modifies the values of primary key columns. If such a change is made, it

** is represented in a changeset as a DELETE followed by an INSERT.

** Changes are not recorded for rows that have NULL values stored in one or

** more of their PRIMARY KEY columns. If such a row is inserted or deleted,

** no corresponding change is present in the changesets returned by this

** function. If an existing row with one or more NULL values stored in

** PRIMARY KEY columns is updated so that all PRIMARY KEY columns are non-NULL,

** only an INSERT is appears in the changeset. Similarly, if an existing row

** with non-NULL PRIMARY KEY values is updated so that one or more of its

** PRIMARY KEY columns are set to NULL, the resulting changeset contains a

** DELETE change only.

** The contents of a changeset may be traversed using an iterator created

** using the [sqlite3changeset_start()] API. A changeset may be applied to

** a database with a compatible schema using the [sqlite3changeset_apply()]

** API.

** Within a changeset generated by this function, all changes related to a

** single table are grouped together. In other words, when iterating through

** a changeset or when applying a changeset to a database, all changes related

** to a single table are processed before moving on to the next table. Tables

** are sorted in the same order in which they were attached (or auto-attached)

** to the sqlite3_session object. The order in which the changes related to

** a single table are stored is undefined.

** Following a successful call to this function, it is the responsibility of

** the caller to eventually free the buffer that *ppChangeset points to using

** [sqlite3_free()].

** <h3>Changeset Generation</h3>

** Once a table has been attached to a session object, the session object

** records the primary key values of all new rows inserted into the table.

** It also records the original primary key and other column values of any

** deleted or updated rows. For each unique primary key value, data is only

** recorded once - the first time a row with said primary key is inserted,

** updated or deleted in the lifetime of the session.

** There is one exception to the previous paragraph: when a row is inserted,

** updated or deleted, if one or more of its primary key columns contain a

** NULL value, no record of the change is made.

** The session object therefore accumulates two types of records - those

** that consist of primary key values only (created when the user inserts

** a new record) and those that consist of the primary key values and the

** original values of other table columns (created when the users deletes

** or updates a record).

** When this function is called, the requested changeset is created using

** both the accumulated records and the current contents of the database

** file. Specifically:

** <ul>

** <li> For each record generated by an insert, the database is queried

** for a row with a matching primary key. If one is found, an INSERT

** change is added to the changeset. If no such row is found, no change

** is added to the changeset.

** <li> For each record generated by an update or delete, the database is

** queried for a row with a matching primary key. If such a row is

** found and one or more of the non-primary key fields have been

** modified from their original values, an UPDATE change is added to

** the changeset. Or, if no such row is found in the table, a DELETE

** change is added to the changeset. If there is a row with a matching

** primary key in the database, but all fields contain their original

** values, no change is added to the changeset.

** </ul>

** This means, amongst other things, that if a row is inserted and then later

** deleted while a session object is active, neither the insert nor the delete

** will be present in the changeset. Or if a row is deleted and then later a

** row with the same primary key values inserted while a session object is

** active, the resulting changeset will contain an UPDATE change instead of

** a DELETE and an INSERT.

** When a session object is disabled (see the [sqlite3session_enable()] API),

** it does not accumulate records when rows are inserted, updated or deleted.

** This may appear to have some counter-intuitive effects if a single row

** is written to more than once during a session. For example, if a row

** is inserted while a session object is enabled, then later deleted while

** the same session object is disabled, no INSERT record will appear in the

** changeset, even though the delete took place while the session was disabled.

** Or, if one field of a row is updated while a session is enabled, and

** then another field of the same row is updated while the session is disabled,

** the resulting changeset will contain an UPDATE change that updates both

** fields.

int sqlite3session_changeset(

sqlite3_session *pSession, /* Session object */

int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */

void **ppChangeset /* OUT: Buffer containing changeset */

);

** CAPI3REF: Return An Upper-limit For The Size Of The Changeset

** METHOD: sqlite3_session

** By default, this function always returns 0. For it to return

** a useful result, the sqlite3_session object must have been configured

** to enable this API using sqlite3session_object_config() with the

** SQLITE_SESSION_OBJCONFIG_SIZE verb.

** When enabled, this function returns an upper limit, in bytes, for the size

** of the changeset that might be produced if sqlite3session_changeset() were

** called. The final changeset size might be equal to or smaller than the

** size in bytes returned by this function.

sqlite3_int64 sqlite3session_changeset_size(sqlite3_session *pSession);

** CAPI3REF: Load The Difference Between Tables Into A Session

** METHOD: sqlite3_session

** If it is not already attached to the session object passed as the first

** argument, this function attaches table zTbl in the same manner as the

** [sqlite3session_attach()] function. If zTbl does not exist, or if it

** does not have a primary key, this function is a no-op (but does not return

** an error).

** Argument zFromDb must be the name of a database ("main", "temp" etc.)

** attached to the same database handle as the session object that contains

** a table compatible with the table attached to the session by this function.

** A table is considered compatible if it:

** <ul>

** <li> Has the same name,

** <li> Has the same set of columns declared in the same order, and

** <li> Has the same PRIMARY KEY definition.

** </ul>

** If the tables are not compatible, SQLITE_SCHEMA is returned. If the tables

** are compatible but do not have any PRIMARY KEY columns, it is not an error

** but no changes are added to the session object. As with other session

** APIs, tables without PRIMARY KEYs are simply ignored.

** This function adds a set of changes to the session object that could be

** used to update the table in database zFrom (call this the "from-table")

** so that its content is the same as the table attached to the session

** object (call this the "to-table"). Specifically:

** <ul>

** <li> For each row (primary key) that exists in the to-table but not in

** the from-table, an INSERT record is added to the session object.

** <li> For each row (primary key) that exists in the to-table but not in

** the from-table, a DELETE record is added to the session object.

** <li> For each row (primary key) that exists in both tables, but features

** different non-PK values in each, an UPDATE record is added to the

** session.

** </ul>

** To clarify, if this function is called and then a changeset constructed

** using [sqlite3session_changeset()], then after applying that changeset to

** database zFrom the contents of the two compatible tables would be

** identical.

** Unless the call to this function is a no-op as described above, it is an

** error if database zFrom does not exist or does not contain the required

** compatible table.

** If the operation is successful, SQLITE_OK is returned. Otherwise, an SQLite

** error code. In this case, if argument pzErrMsg is not NULL, *pzErrMsg

** may be set to point to a buffer containing an English language error

** message. It is the responsibility of the caller to free this buffer using

** sqlite3_free().

int sqlite3session_diff(

sqlite3_session *pSession,

const char *zFromDb,

const char *zTbl,

char **pzErrMsg

);

** CAPI3REF: Generate A Patchset From A Session Object

** METHOD: sqlite3_session

** The differences between a patchset and a changeset are that:

** <ul>

** <li> DELETE records consist of the primary key fields only. The

** original values of other fields are omitted.

** <li> The original values of any modified fields are omitted from

** UPDATE records.

** </ul>

** A patchset blob may be used with up to date versions of all

** sqlite3changeset_xxx API functions except for sqlite3changeset_invert(),

** which returns SQLITE_CORRUPT if it is passed a patchset. Similarly,

** attempting to use a patchset blob with old versions of the

** sqlite3changeset_xxx APIs also provokes an SQLITE_CORRUPT error.

** Because the non-primary key "old.*" fields are omitted, no

** SQLITE_CHANGESET_DATA conflicts can be detected or reported if a patchset

** is passed to the sqlite3changeset_apply() API. Other conflict types work

** in the same way as for changesets.

** Changes within a patchset are ordered in the same way as for changesets

** generated by the sqlite3session_changeset() function (i.e. all changes for

** a single table are grouped together, tables appear in the order in which

** they were attached to the session object).

int sqlite3session_patchset(

sqlite3_session *pSession, /* Session object */

int *pnPatchset, /* OUT: Size of buffer at *ppPatchset */

void **ppPatchset /* OUT: Buffer containing patchset */

);

** CAPI3REF: Test if a changeset has recorded any changes.

** Return non-zero if no changes to attached tables have been recorded by

** the session object passed as the first argument. Otherwise, if one or

** more changes have been recorded, return zero.

** Even if this function returns zero, it is possible that calling

** [sqlite3session_changeset()] on the session handle may still return a

** changeset that contains no changes. This can happen when a row in

** an attached table is modified and then later on the original values

** are restored. However, if this function returns non-zero, then it is

** guaranteed that a call to sqlite3session_changeset() will return a

** changeset containing zero changes.

int sqlite3session_isempty(sqlite3_session *pSession);

** CAPI3REF: Query for the amount of heap memory used by a session object.

** This API returns the total amount of heap memory in bytes currently

** used by the session object passed as the only argument.

sqlite3_int64 sqlite3session_memory_used(sqlite3_session *pSession);

** CAPI3REF: Create An Iterator To Traverse A Changeset

** CONSTRUCTOR: sqlite3_changeset_iter

** Create an iterator used to iterate through the contents of a changeset.

** If successful, *pp is set to point to the iterator handle and SQLITE_OK

** is returned. Otherwise, if an error occurs, *pp is set to zero and an

** SQLite error code is returned.

** The following functions can be used to advance and query a changeset

** iterator created by this function:

** <ul>

** <li> [sqlite3changeset_next()]

** <li> [sqlite3changeset_op()]

** <li> [sqlite3changeset_new()]

** <li> [sqlite3changeset_old()]

** </ul>

** It is the responsibility of the caller to eventually destroy the iterator

** by passing it to [sqlite3changeset_finalize()]. The buffer containing the

** changeset (pChangeset) must remain valid until after the iterator is

** destroyed.

** Assuming the changeset blob was created by one of the

** [sqlite3session_changeset()], [sqlite3changeset_concat()] or

** [sqlite3changeset_invert()] functions, all changes within the changeset

** that apply to a single table are grouped together. This means that when

** an application iterates through a changeset using an iterator created by

** this function, all changes that relate to a single table are visited

** consecutively. There is no chance that the iterator will visit a change

** the applies to table X, then one for table Y, and then later on visit

** another change for table X.

** The behavior of sqlite3changeset_start_v2() and its streaming equivalent

** may be modified by passing a combination of

** [SQLITE_CHANGESETSTART_INVERT | supported flags] as the 4th parameter.

** Note that the sqlite3changeset_start_v2() API is still <b>experimental</b>

** and therefore subject to change.

int sqlite3changeset_start(

sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */

int nChangeset, /* Size of changeset blob in bytes */

void *pChangeset /* Pointer to blob containing changeset */

);

int sqlite3changeset_start_v2(

sqlite3_changeset_iter **pp, /* OUT: New changeset iterator handle */

int nChangeset, /* Size of changeset blob in bytes */

void *pChangeset, /* Pointer to blob containing changeset */

int flags /* SESSION_CHANGESETSTART_* flags */

);

** CAPI3REF: Flags for sqlite3changeset_start_v2

** The following flags may passed via the 4th parameter to

** [sqlite3changeset_start_v2] and [sqlite3changeset_start_v2_strm]:

** <dt>SQLITE_CHANGESETSTART_INVERT <dd>

** Invert the changeset while iterating through it. This is equivalent to

** inverting a changeset using sqlite3changeset_invert() before applying it.

** It is an error to specify this flag with a patchset.

#define SQLITE_CHANGESETSTART_INVERT 0x0002

** CAPI3REF: Advance A Changeset Iterator

** METHOD: sqlite3_changeset_iter

** This function may only be used with iterators created by the function

** [sqlite3changeset_start()]. If it is called on an iterator passed to

** a conflict-handler callback by [sqlite3changeset_apply()], SQLITE_MISUSE

** is returned and the call has no effect.

** Immediately after an iterator is created by sqlite3changeset_start(), it

** does not point to any change in the changeset. Assuming the changeset

** is not empty, the first call to this function advances the iterator to

** point to the first change in the changeset. Each subsequent call advances

** the iterator to point to the next change in the changeset (if any). If

** no error occurs and the iterator points to a valid change after a call

** to sqlite3changeset_next() has advanced it, SQLITE_ROW is returned.

** Otherwise, if all changes in the changeset have already been visited,

** SQLITE_DONE is returned.

** If an error occurs, an SQLite error code is returned. Possible error

** codes include SQLITE_CORRUPT (if the changeset buffer is corrupt) or

** SQLITE_NOMEM.

int sqlite3changeset_next(sqlite3_changeset_iter *pIter);

** CAPI3REF: Obtain The Current Operation From A Changeset Iterator

** METHOD: sqlite3_changeset_iter

** The pIter argument passed to this function may either be an iterator

** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator

** created by [sqlite3changeset_start()]. In the latter case, the most recent

** call to [sqlite3changeset_next()] must have returned [SQLITE_ROW]. If this

** is not the case, this function returns [SQLITE_MISUSE].

** Arguments pOp, pnCol and pzTab may not be NULL. Upon return, three

** outputs are set through these pointers:

** *pOp is set to one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],

** depending on the type of change that the iterator currently points to;

** *pnCol is set to the number of columns in the table affected by the change; and

** *pzTab is set to point to a nul-terminated utf-8 encoded string containing

** the name of the table affected by the current change. The buffer remains

** valid until either sqlite3changeset_next() is called on the iterator

** or until the conflict-handler function returns.

** If pbIndirect is not NULL, then *pbIndirect is set to true (1) if the change

** is an indirect change, or false (0) otherwise. See the documentation for

** [sqlite3session_indirect()] for a description of direct and indirect

** changes.

** If no error occurs, SQLITE_OK is returned. If an error does occur, an

** SQLite error code is returned. The values of the output variables may not

** be trusted in this case.

int sqlite3changeset_op(

sqlite3_changeset_iter *pIter, /* Iterator object */

const char **pzTab, /* OUT: Pointer to table name */

int *pnCol, /* OUT: Number of columns in table */

int *pOp, /* OUT: SQLITE_INSERT, DELETE or UPDATE */

int *pbIndirect /* OUT: True for an 'indirect' change */

);

** CAPI3REF: Obtain The Primary Key Definition Of A Table

** METHOD: sqlite3_changeset_iter

** For each modified table, a changeset includes the following:

** <ul>

** <li> The number of columns in the table, and

** <li> Which of those columns make up the tables PRIMARY KEY.

** </ul>

** This function is used to find which columns comprise the PRIMARY KEY of

** the table modified by the change that iterator pIter currently points to.

** If successful, *pabPK is set to point to an array of nCol entries, where

** nCol is the number of columns in the table. Elements of *pabPK are set to

** 0x01 if the corresponding column is part of the tables primary key, or

** 0x00 if it is not.

** If argument pnCol is not NULL, then *pnCol is set to the number of columns

** in the table.

** If this function is called when the iterator does not point to a valid

** entry, SQLITE_MISUSE is returned and the output variables zeroed. Otherwise,

** SQLITE_OK is returned and the output variables populated as described

** above.

int sqlite3changeset_pk(

sqlite3_changeset_iter *pIter, /* Iterator object */

unsigned char **pabPK, /* OUT: Array of boolean - true for PK cols */

int *pnCol /* OUT: Number of entries in output array */

);

** CAPI3REF: Obtain old.* Values From A Changeset Iterator

** METHOD: sqlite3_changeset_iter

** The pIter argument passed to this function may either be an iterator

** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator

** created by [sqlite3changeset_start()]. In the latter case, the most recent

** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.

** Furthermore, it may only be called if the type of change that the iterator

** currently points to is either [SQLITE_DELETE] or [SQLITE_UPDATE]. Otherwise,

** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.

** Argument iVal must be greater than or equal to 0, and less than the number

** of columns in the table affected by the current change. Otherwise,

** [SQLITE_RANGE] is returned and *ppValue is set to NULL.

** If successful, this function sets *ppValue to point to a protected

** sqlite3_value object containing the iVal'th value from the vector of

** original row values stored as part of the UPDATE or DELETE change and

** returns SQLITE_OK. The name of the function comes from the fact that this

** is similar to the "old.*" columns available to update or delete triggers.

** If some other error occurs (e.g. an OOM condition), an SQLite error code

** is returned and *ppValue is set to NULL.

int sqlite3changeset_old(

sqlite3_changeset_iter *pIter, /* Changeset iterator */

int iVal, /* Column number */

sqlite3_value **ppValue /* OUT: Old value (or NULL pointer) */

);

** CAPI3REF: Obtain new.* Values From A Changeset Iterator

** METHOD: sqlite3_changeset_iter

** The pIter argument passed to this function may either be an iterator

** passed to a conflict-handler by [sqlite3changeset_apply()], or an iterator

** created by [sqlite3changeset_start()]. In the latter case, the most recent

** call to [sqlite3changeset_next()] must have returned SQLITE_ROW.

** Furthermore, it may only be called if the type of change that the iterator

** currently points to is either [SQLITE_UPDATE] or [SQLITE_INSERT]. Otherwise,

** this function returns [SQLITE_MISUSE] and sets *ppValue to NULL.

** Argument iVal must be greater than or equal to 0, and less than the number

** of columns in the table affected by the current change. Otherwise,

** [SQLITE_RANGE] is returned and *ppValue is set to NULL.

** If successful, this function sets *ppValue to point to a protected

** sqlite3_value object containing the iVal'th value from the vector of

** new row values stored as part of the UPDATE or INSERT change and

** returns SQLITE_OK. If the change is an UPDATE and does not include

** a new value for the requested column, *ppValue is set to NULL and

** SQLITE_OK returned. The name of the function comes from the fact that

** this is similar to the "new.*" columns available to update or delete

** triggers.

** If some other error occurs (e.g. an OOM condition), an SQLite error code

** is returned and *ppValue is set to NULL.

int sqlite3changeset_new(

sqlite3_changeset_iter *pIter, /* Changeset iterator */

int iVal, /* Column number */

sqlite3_value **ppValue /* OUT: New value (or NULL pointer) */

);

** CAPI3REF: Obtain Conflicting Row Values From A Changeset Iterator

** METHOD: sqlite3_changeset_iter

** This function should only be used with iterator objects passed to a

** conflict-handler callback by [sqlite3changeset_apply()] with either

** [SQLITE_CHANGESET_DATA] or [SQLITE_CHANGESET_CONFLICT]. If this function

** is called on any other iterator, [SQLITE_MISUSE] is returned and *ppValue

** is set to NULL.

** Argument iVal must be greater than or equal to 0, and less than the number

** of columns in the table affected by the current change. Otherwise,

** [SQLITE_RANGE] is returned and *ppValue is set to NULL.

** If successful, this function sets *ppValue to point to a protected

** sqlite3_value object containing the iVal'th value from the

** "conflicting row" associated with the current conflict-handler callback

** and returns SQLITE_OK.

** If some other error occurs (e.g. an OOM condition), an SQLite error code

** is returned and *ppValue is set to NULL.

int sqlite3changeset_conflict(

sqlite3_changeset_iter *pIter, /* Changeset iterator */

int iVal, /* Column number */

sqlite3_value **ppValue /* OUT: Value from conflicting row */

);

** CAPI3REF: Determine The Number Of Foreign Key Constraint Violations

** METHOD: sqlite3_changeset_iter

** This function may only be called with an iterator passed to an

** SQLITE_CHANGESET_FOREIGN_KEY conflict handler callback. In this case

** it sets the output variable to the total number of known foreign key

** violations in the destination database and returns SQLITE_OK.

** In all other cases this function returns SQLITE_MISUSE.

int sqlite3changeset_fk_conflicts(

sqlite3_changeset_iter *pIter, /* Changeset iterator */

int *pnOut /* OUT: Number of FK violations */

);

** CAPI3REF: Finalize A Changeset Iterator

** METHOD: sqlite3_changeset_iter

** This function is used to finalize an iterator allocated with

** [sqlite3changeset_start()].

** This function should only be called on iterators created using the

** [sqlite3changeset_start()] function. If an application calls this

** function with an iterator passed to a conflict-handler by

** [sqlite3changeset_apply()], [SQLITE_MISUSE] is immediately returned and the

** call has no effect.

** If an error was encountered within a call to an sqlite3changeset_xxx()

** function (for example an [SQLITE_CORRUPT] in [sqlite3changeset_next()] or an

** [SQLITE_NOMEM] in [sqlite3changeset_new()]) then an error code corresponding

** to that error is returned by this function. Otherwise, SQLITE_OK is

** returned. This is to allow the following pattern (pseudo-code):

** <pre>

** sqlite3changeset_start();

** while( SQLITE_ROW==sqlite3changeset_next() ){

** // Do something with change.

** }

** rc = sqlite3changeset_finalize();

** if( rc!=SQLITE_OK ){

** // An error has occurred

** }

** </pre>

int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);

** CAPI3REF: Invert A Changeset

** This function is used to "invert" a changeset object. Applying an inverted

** changeset to a database reverses the effects of applying the uninverted

** changeset. Specifically:

** <ul>

** <li> Each DELETE change is changed to an INSERT, and

** <li> Each INSERT change is changed to a DELETE, and

** <li> For each UPDATE change, the old.* and new.* values are exchanged.

** </ul>

** This function does not change the order in which changes appear within

** the changeset. It merely reverses the sense of each individual change.

** If successful, a pointer to a buffer containing the inverted changeset

** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and

** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are

** zeroed and an SQLite error code returned.

** It is the responsibility of the caller to eventually call sqlite3_free()

** on the *ppOut pointer to free the buffer allocation following a successful

** call to this function.

** WARNING/TODO: This function currently assumes that the input is a valid

** changeset. If it is not, the results are undefined.

int sqlite3changeset_invert(

int nIn, const void *pIn, /* Input changeset */

int *pnOut, void **ppOut /* OUT: Inverse of input */

);

** CAPI3REF: Concatenate Two Changeset Objects

** This function is used to concatenate two changesets, A and B, into a

** single changeset. The result is a changeset equivalent to applying

** changeset A followed by changeset B.

** This function combines the two input changesets using an

** sqlite3_changegroup object. Calling it produces similar results as the

** following code fragment:

** <pre>

** sqlite3_changegroup *pGrp;

** rc = sqlite3_changegroup_new(&pGrp);

** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nA, pA);

** if( rc==SQLITE_OK ) rc = sqlite3changegroup_add(pGrp, nB, pB);

** if( rc==SQLITE_OK ){

** rc = sqlite3changegroup_output(pGrp, pnOut, ppOut);

** }else{

** *ppOut = 0;

** *pnOut = 0;

** }

** </pre>

** Refer to the sqlite3_changegroup documentation below for details.

int sqlite3changeset_concat(

int nA, /* Number of bytes in buffer pA */

void *pA, /* Pointer to buffer containing changeset A */

int nB, /* Number of bytes in buffer pB */

void *pB, /* Pointer to buffer containing changeset B */

int *pnOut, /* OUT: Number of bytes in output changeset */

void **ppOut /* OUT: Buffer containing output changeset */

);

** CAPI3REF: Changegroup Handle

** A changegroup is an object used to combine two or more

** [changesets] or [patchsets]

typedef struct sqlite3_changegroup sqlite3_changegroup;

** CAPI3REF: Create A New Changegroup Object

** CONSTRUCTOR: sqlite3_changegroup

** An sqlite3_changegroup object is used to combine two or more changesets

** (or patchsets) into a single changeset (or patchset). A single changegroup

** object may combine changesets or patchsets, but not both. The output is

** always in the same format as the input.

** If successful, this function returns SQLITE_OK and populates (*pp) with

** a pointer to a new sqlite3_changegroup object before returning. The caller

** should eventually free the returned object using a call to

** sqlite3changegroup_delete(). If an error occurs, an SQLite error code

** (i.e. SQLITE_NOMEM) is returned and *pp is set to NULL.

** The usual usage pattern for an sqlite3_changegroup object is as follows:

** <ul>

** <li> It is created using a call to sqlite3changegroup_new().

** <li> Zero or more changesets (or patchsets) are added to the object

** by calling sqlite3changegroup_add().

** <li> The result of combining all input changesets together is obtained

** by the application via a call to sqlite3changegroup_output().

** <li> The object is deleted using a call to sqlite3changegroup_delete().

** </ul>

** Any number of calls to add() and output() may be made between the calls to

** new() and delete(), and in any order.

** As well as the regular sqlite3changegroup_add() and

** sqlite3changegroup_output() functions, also available are the streaming

** versions sqlite3changegroup_add_strm() and sqlite3changegroup_output_strm().

int sqlite3changegroup_new(sqlite3_changegroup **pp);

** CAPI3REF: Add a Schema to a Changegroup

** METHOD: sqlite3_changegroup_schema

** This method may be used to optionally enforce the rule that the changesets

** added to the changegroup handle must match the schema of database zDb

** ("main", "temp", or the name of an attached database). If

** sqlite3changegroup_add() is called to add a changeset that is not compatible

** with the configured schema, SQLITE_SCHEMA is returned and the changegroup

** object is left in an undefined state.

** A changeset schema is considered compatible with the database schema in

** the same way as for sqlite3changeset_apply(). Specifically, for each

** table in the changeset, there exists a database table with:

** <ul>

** <li> The name identified by the changeset, and

** <li> at least as many columns as recorded in the changeset, and

** <li> the primary key columns in the same position as recorded in

** the changeset.

** </ul>

** The output of the changegroup object always has the same schema as the

** database nominated using this function. In cases where changesets passed

** to sqlite3changegroup_add() have fewer columns than the corresponding table

** in the database schema, these are filled in using the default column

** values from the database schema. This makes it possible to combined

** changesets that have different numbers of columns for a single table

** within a changegroup, provided that they are otherwise compatible.

int sqlite3changegroup_schema(sqlite3_changegroup*, sqlite3*, const char *zDb);

** CAPI3REF: Add A Changeset To A Changegroup

** METHOD: sqlite3_changegroup

** Add all changes within the changeset (or patchset) in buffer pData (size

** nData bytes) to the changegroup.

** If the buffer contains a patchset, then all prior calls to this function

** on the same changegroup object must also have specified patchsets. Or, if

** the buffer contains a changeset, so must have the earlier calls to this

** function. Otherwise, SQLITE_ERROR is returned and no changes are added

** to the changegroup.

** Rows within the changeset and changegroup are identified by the values in

** their PRIMARY KEY columns. A change in the changeset is considered to

** apply to the same row as a change already present in the changegroup if

** the two rows have the same primary key.

** Changes to rows that do not already appear in the changegroup are

** simply copied into it. Or, if both the new changeset and the changegroup

** contain changes that apply to a single row, the final contents of the

** changegroup depends on the type of each change, as follows:

** <table border=1 style="margin-left:8ex;margin-right:8ex">

** <tr><th style="white-space:pre">Existing Change </th>

** <th style="white-space:pre">New Change </th>

** <th>Output Change

** <tr><td>INSERT <td>INSERT <td>

** The new change is ignored. This case does not occur if the new

** changeset was recorded immediately after the changesets already

** added to the changegroup.

** <tr><td>INSERT <td>UPDATE <td>

** The INSERT change remains in the changegroup. The values in the

** INSERT change are modified as if the row was inserted by the

** existing change and then updated according to the new change.

View remainder of file in raw view

sqlcipher/ext/session/sqlite3session.h at sqlite-release · sqlcipher/sqlcipher · GitHub

Uh oh!

Expand file tree

Breadcrumbs

sqlite3session.h

Latest commit

History

Breadcrumbs

sqlite3session.h

File metadata and controls