updown/distribute/include/files.h

/*********************************************************************
    *文件说明: 加断电保护+版本校验的文件读写接口
    *作者: logos
    *日期: 2018/11/17
    *修改日志:  2018/11/17 logos 创建


    *PS: 本模块接口都是单线程执行，多线程调用时请自行增加保护机制
         本模块主要为了防止文件读写错误时丢失原文件问题，效率相比系统API会更低一些
         open文件时，如果标识了版本号，则文件会自动校验完整性，不完整时，会把所有内容全部丢弃
***********************************************************************/
#pragma once
#ifndef DLL_INCLUDE_FILES_H
#define DLL_INCLUDE_FILES_H

#ifndef EXPORT_C
#define EXPORT_C extern "C"
#endif

#ifndef WINAPI
#define WINAPI __stdcall
#endif

#ifndef uint
#define uint unsigned int
#endif

class ifiles
{//文件操作类
public:
    /****************************************************
        *Function: 打开文件 -- 打开后游标默认在起始位置
        *Intput:   file 文件全路径，包括后缀
                   version 文件版本号，默认为0则不设置版本号校验
        *Output:   NULL
        *Return:   成功返回0 ，失败返回错误码
    ******************************************************/
    virtual int Open(const char* file, int version = 0) = 0;

    /****************************************************
        *Function: 关闭文件,会自动刷新到硬盘
        *Intput:   NULL
        *Output:   NULL
        *Return:   成功返回文件句柄 ，失败返回NULL
    ******************************************************/
    virtual int Close() = 0;

    /****************************************************
        *Function: 清空文件内容
        *Intput:   NULL
        *Output:   NULL
        *Return:   成功返回0，失败返回错误码
    ******************************************************/
    virtual int Clear() = 0;
    
    /****************************************************
        *Function: 读取当前游标大小 -- 与ftell类似调用方式
        *Intput:   NULL
        *Output:   NULL
        *Return:   成功返回当前游标位置>=0，失败返回错误码<0
    ******************************************************/
    virtual int Pos() = 0;
    
    /****************************************************
        *Function: 读取当前文件实际大小
        *Intput:   NULL
        *Output:   NULL
        *Return:   成功返回大小>=0，失败返回错误码<0
    ******************************************************/
    virtual int Size() = 0;

    /****************************************************
        *Function: 判断当前游标是否已经到达文件末尾 -- 与feof类似调用方式
        *Intput:   NULL
        *Output:   NULL
        *Return:   已经到达末尾返回1，否则返回0
    ******************************************************/
    virtual int IsEof() = 0;

    /****************************************************
        *Function: 设置当前游标位置 -- 与fseek类似调用方式
        *Intput:   offset 基于_Origin的偏移量
                   _Origin SEEK_SET-文件头 SEEK_END-文件末尾 SEEK_CUR-当前位置
        *Output:   NULL
        *Return:   成功返回0，失败返回错误码
    ******************************************************/
    virtual int Seek(int offset, int _Origin) = 0;
    
    /****************************************************
        *Function: 设置当前游标位置到第几行?
        *Intput:   nline 基于起始位置第几行?
        *Output:   NULL
        *Return:   成功返回0，失败返回错误码
        *PS: 此接口仅对ascii文件有效
    ******************************************************/
    virtual int SeekLine(int nline) = 0;

    /****************************************************
        *Function: 立即将文件内容保存到硬盘 -- 与fflush类似调用方式
        *Intput:   NULL
        *Output:   NULL
        *Return:   成功返回0，失败返回错误码
    ******************************************************/
    virtual int Flush() = 0;

    /****************************************************
        *Function: 从文件读取一行字符串 -- 与fgets类似调用方式
        *Intput:   psz 读取缓冲区
                   maxcnt 希望读取的大小
        *Output:   NULL
        *Return:   成功返回读取到的字节长度，失败返回错误码<=0
        *PS: 遇到\r\n\0都认为读取结束.
    ******************************************************/
    virtual int Reads(char* psz, uint maxcnt) = 0;

    /****************************************************
        *Function: 写入字符串到文件 -- 与fputs类似调用方式
        *Intput:   psz 待写入字符串
        *Output:   NULL
        *Return:   成功返回0，失败返回错误码<0
        *PS: 不会自动写入\r\n
    ******************************************************/
    virtual int Writes(const char* psz) = 0;

    /****************************************************
        *Function: 从文件读取数据 -- 与fread类似调用方式
        *Intput:   psz 读取缓冲区
                   maxcnt 希望读取的大小
        *Output:   NULL
        *Return:   成功返回读取到的字节长度，失败返回错误码<=0
    ******************************************************/
    virtual int Read(void* psz, uint maxcnt) = 0;

    /****************************************************
        *Function: 写入数据到文件 -- 与fwrite类似调用方式
        *Intput:   psz 待写入数据块
                   ncnt 待写入大小
        *Output:   NULL
        *Return:   成功返回0，失败返回错误码<0
    ******************************************************/
    virtual int Write(const void* psz, uint ncnt) = 0;
};

//导出接口
EXPORT_C int WINAPI ifiles_open(ifiles* p, const char* file, int version = 0);
EXPORT_C int WINAPI ifiles_close(ifiles* p);
EXPORT_C int WINAPI ifiles_clear(ifiles* p);
EXPORT_C int WINAPI ifiles_pos(ifiles* p);
EXPORT_C int WINAPI ifiles_size(ifiles* p);
EXPORT_C int WINAPI ifiles_iseof(ifiles* p);
EXPORT_C int WINAPI ifiles_flush(ifiles* p);
EXPORT_C int WINAPI ifiles_seek(ifiles* p, int offset, int _origin);
EXPORT_C int WINAPI ifiles_seek_line(ifiles* p, int nline);
EXPORT_C int WINAPI ifiles_reads(ifiles* p, char* psz, uint maxcnt);
EXPORT_C int WINAPI ifiles_writes(ifiles* p, const char* psz);
EXPORT_C int WINAPI ifiles_read(ifiles* p, void* psz, uint maxcnt);
EXPORT_C int WINAPI ifiles_write(ifiles* p, const void* psz, uint ncnt);

/****************************************************
    *Function: 创建file对象
    *Intput:   NULL
    *Output:   h file对象指针
    *Return:   成功返回0 ，失败返回错误码
******************************************************/
EXPORT_C int WINAPI CreateFiles(ifiles** h);

/****************************************************
    *Function: 释放file对象
    *Intput:   NULL
    *Output:   h file对象指针
    *Return:   成功返回0 ，失败返回错误码
******************************************************/
EXPORT_C int WINAPI ReleaseFiles(ifiles** h);

#endif  //防止重复包含头文件