LOADDATABLOCK

Представляет собой блок управляющих и конфигурирующих данных, представляющих собой "загрузку" или сборник загрузок.
В документации данная структура может сокращённо обозначаться "LDB".

struct LOADDATABLOCK
{
    struct CURLWRITEDATA
    {   //стркутура данных функции записи. Для системных нужд.
        LOADDATABLOCK *pLDB; //указатель на родительский LOADDATABLOCK
        char active; //маркер использования
        CURL *handle; //CURL easy указатель ведущий обмен
        HRESULT hr; //код ошибки, если таковые возникают.
        unsigned __int64 wrote; //размер принимаемого блока и число записанных байт
        unsigned __int64 dat_in, dat_sz; //определяет начало и размер области приёма
        char range[42]; //завершающаяся нулём строка, содержащая запрошенный диапазон. Нужна для CURL.
    };
    struct RDY{ //
Для системных нужд.
        const unsigned __int64 in, out; //границы (байт) готового блока
    };
    const void *item; //указатель на элемент списка, с которым ассоциирована эта структура
    char *url; //целевой адрес приёма
    wchar_t *sPath; //путь к целевому файлу
    HANDLE stream; //целевой файл или char* буфер памяти, см описание flags->0x2
    char *UserAgent; //переопределяет стандартный юзерагент, если важно
    char *Headers; //пачка особых заголовков HTTP/FTP, если важны.
    char *cookies; //пачка кук, загоняемых/переданных сервером.
    const char state; //состояние загрузки
    const unsigned char mpNoAllow; //флаговое поле блокировки порождения пиров
    unsigned short flags; //набор флагов - настроек и идентификаторов
    struct LOG
    {    //структура отвечающая за "консольный" вывод данных
        const HANDLE hRlog; //указатель чтения потока.
        FILE *fWlog; //указатель записи потока, укакованный в FILE
        const char *mem; //массив памяти, накапливающий данные
        const size_t memsz; //размер этого массива
    } const log;
    const LOADDATABLOCK *link;
    const COMMTHRDSTRUCT *pInCom;
    const unsigned __int64 dat_all; //полный размер принимаемого блока
    const unsigned __int64 dat_recv; //принятый объём байт.
    const unsigned __int64 LastRecv; //значение dat_recv в последнюю оценку скорости
    const DWORD  LastTime; //значение времени в момент предыдущего принятого блока
    unsigned char nCWDs; //число разрешённых к задействованию потоков/структур
CURLWRITEDATA
    const unsigned char nCWRalloc;//указывает число распределённых блков в pCWD и pRdy
    const unsigned char nRdy; //число принятых участков данных / число загружающихся дочерних в текущий момент
    union{
        const CURLWRITEDATA *pCWD; //структуры данных пира
        const size_t nChilds; //число привязанных дочерних
    }const cc;
    union {
        const RDY *pRdy; //указывает участки ранее принятых данных уже закрытыми пирами
        const size_t nRdyChilds; //число уже загруженных дочерних
    }const ra;//объединения cc и ra: если flags & FLGSGROUPMASTR == 0 - блоки pCWD и pRdy, в противном случае nChilds и nActvChilds
    const long unused[6];
    size_t IDplugin; //указка-идентификатор плагина
    void *pAdv; //Указка на начало данных плагина.
};


item
catID данной загрузки (связь с интерфейсом пользователя). Для системных нужд.
url
Целевой URL адрес для загрузки данных. Он может сам измениться в процессе загрузки.
sPath
Путь/файл в который будет производиться запись принимаемых данных.
stream
Указатель открытого файла по sPath или char* буфер памяти. Зависит от состояния флага FLGSUSERAM. Может быть равен 0 если загрузка остановлена или нету данных.
UserAgent
Строка - передаваемый серверу особый HTTP заголовок USER-AGENT. Если равен 0 - будет передан стандартный.
Headers
Пачка особых заголовков HTTP/FTP. (пока не реализовано), на выходе по окончании передачи содержит HTTP заголовок ответа сервера (реализовано).
cookies
Список кук, посылаемых серверу или переданных сервером. Он может сам меняться в процессе загрузки.
state
Индикатор состояния загрузки. Подробней описано ниже.
mpNoAllow
Флаговое поле блокировки порождения пиров. Для системных нужд.
flags
Набор флагов - настроек и идентификаторов. Подробней описано ниже.
log
Субструктура отвечающая за "консольный" вывод данных.
     hRlog
Зарезервировано системой.
     fWlog
Поток записи в лог (например для подачи в fprintf()).Может быть равен 0 (как признак перегрузки системы числом работающих загрузок).
     mem
Массив памяти, содержащий текст лога.
     memsz
Размер массива mem (байт).
link
Зарезервировано системой.
pInCom
Зарезервировано системой.
dat_all
Полный размер принимаемого блока. Может быть равен 0 если этот размер неизвестен.
dat_recv
Принятый объём байт.
LastRecv
Значение dat_recv в последнюю оценку скорости.
LastTime
Значение времени в момент последней записи LastRecv. Вместе с LastRecv применимо для оценки скорости передачи данных.
nCWDs
Максимально допустимое количество пиров на данную загрузку.
Т.е. не более скольки подключений может сделать загрузчик к серверу для получения данных по указанному URL. Для больших файлов рекомендовано 5, для мелких и запросов веб-страниц - 1. В любом случае не более 10, как правило "хорошего тона" в среде Веб.
Однако отмечу что это не гарантия что загрузка будет идти на этом числе пиров - помимо целевой Веб сервер может сам ограничивать это количество.
nCWRalloc
Число структур pCWD и pRdy (не сумма! а их количества. Они всегда равны друг-другу)
nRdy
Если установлен флаг FLGSGROUPMASTR, число загружающихся дочерних загрузок в текущий момент, иначе - для системных нужд.
cc
Объединение, содержащее поле nChilds, если установлен флаг FLGSGROUPMASTR, иначе системные данные.
     pCWD
Зарезервировано системой.
     nChilds
Число привязанных дочерних загрузок к данной родительской группе.
ra
Объединение, содержащее поле nRdyChilds, если установлен флаг FLGSGROUPMASTR, иначе системные данные.
     pRdy Зарезервировано системой.
     nRdyChilds
Число уже загруженных дочерних загрузок.
unused
Зарезервировано системой.
IDplugin
Идентификатор твоего плагина в системе.
Или -1 или 0 как признак загрузки, не относящейся ни к одному плагину.
Значение данного поля допустимо изменить в -1 или 0 для отказа от дальнейшего ведения данной загрузки.
pAdv
Предназначено для нужд пользователя. Система никак не оперирует данными этого поля.
При создании, если загрузка создавалась с запросом экстра-байт  - содержит указатель на первый байт за структурой (&pAdv + sizeof(void*)), иначе равно 0.
[]
За структурой могут находится экстра-байты, число которых определяется их числом, запрашиваемым при создании загрузки.

Заметки

Всё что помечено const предназначено только для чтения! В противном случае это приведёт к серьёзным сбоям в работе программы.
Все пользовательские строковые данные (url, sPath, stream(как буфер), UserAgent, Headers, cookies) должны устанавливаться адресами буферов памяти (содержащими строки) созданных вызовом Win32API функции LocalAlloc() с флагом LMEM_FIXED.

state:

Данное поле содержит значения, определяющие состояние загрузки:
-3 Загружена и ожидает реакции пользователя (с соответствующим "состоянием" в окне программы. (выставляется по запросу плагина в HasAction).
-2 Загружена (все данные успешно приняты/переданы)
-1 Свободна/отключена/сбой. Если наблюдается это состояние после запуска загрузки - стоит расценивать как системный сбой, иначе игнорируй это значение.
0 Остановлена. Операции не производятся, но нет подтверждения что все данные приняты. Сама может переходить в это состояние если пользователь нажал "Стоп" или возникла ошибка передачи данных.
Во всех остальных состояниях ЛЮБЫЕ поля структуры, кроме pAdv и IDplugin, изменять ЗАПРЕЩЕНО.
1
Поставлена на загрузку (ожидает установления связи с сервером)
2
Загружается (пребывает в активной фазе обмена данными)
3
Поставлена на остановку (состояние запроса на прерывание обмена)
4
Останавливается (находится в процессе штатного прекращения связи с сервером)
17
Тоже что 1, но форсированно, игнорируя максимальное число работающих (применяется в системе для выполнения мелких запросов, см. UM_STARTLOAD и StartLDB)

mpNoAllow:

Если не равно нулю - по какой-либо причине было запрещено порождение новых пиров, узнать которую (которые) можно по взведённому состоянию битов:
FMNANOTMP
Сервер не поддерживает качать в много пиров.
FMNANOTRSUME
Сервер не поддерживает докачку.
FMNATSLESSNR
При попытке создать пир обнаружилось что наибольший размер остатка (не загруженного) меньше рационально разумного для создания сокращением объёма для загрузки у уже существующих пиров.(т.е. качать осталось совсем чуть-чуть).
FMNAWAITPEER
Флаг-указатель факта что новый пир заполнен, установлен и ожидается реакция сервера. Блокирует создание новых пиров до тех пор пока сервер не отреагирует на текущий создаваемый.
FMNAPALLINUSE
Достигнуто предельное число пиров на загрузку.
FMNADISABLEMP
Указка, что процессор загрузки фиксировал в запрос одним пиром в ответ на внутренние события процесса передачи (например в результате HTTP ошибки сервера  >= 300.

flags:

Битовое поле, настраивающее работу загрузки. Его флаги могут как изменяться системой так и в рамках работы плагина.
FLGSNORESUME
Флаг-указка, что сервер отвергает RESUME_FROM запрос, но согласен с RANGE запросом при докачке или создании следующего пира.
FLGSUSERAM
Загрузка в память. В таком случае stream - (char*) указатель на буфер в памяти, dat_all - размер этого буфера, он может как нарастать в процессе загрузки так и распределится сразу, если сервер указал объём.
Эта память выделяется LocalAlloc() и сама освобождается при удалении или сбросе загрузки.
Не стоит устанавливать этот флаг если есть опасения что сервер ответит значительным объём данных (мегабайты), в противном случае может привести проблемам производительности.
FLGSTHISAUTO
Подавляет автоматическое следование перенаправлениям (в ответ на 3xx HTTP ошибку система по наличию загрузит страничку - занавеску с сервера и завершит передачу с ошибкой)
Заметка: месить его с FLGSUSERAM следует с осторожностью т. к. сервер (неожиданно) может ответить 2xx ошибкой и большим объёмом данных (целевым файлом например). С другой стороны, при дальнейшем возобновлении работы следует или самостоятельно избавиться от конечного файла (который в любом случае будет создан и возможно заполнен страничкой ошибки перенаправления с сервера) или просто установить флаг FLGSOVERWRITE с целью тихой перезаписи конечного файла.
А также имеет чисто информационный смысл: промежуточно запрошенная загрузка (поставлена плагином с целью запросить с сервера нужные ей дополнительные данные).
FLGSUPLOAD
Выгрузка (upload) - всё на оборот - эти данные заталкиваются на сервер. (пока не реализовано).
FLGSOVERWRITE
Указание перезаписать уже существующие данные по указанным путям (файл или память). (В противном случае загрузка останавливается с ошибкой наличия целевого файла. Штатно пользователю выводится запрос на замену файла, в результате ответа на который система сама может установить этот флаг и перезапустить загрузку)
FLGSGROUP
Указание что эта загрузка находится в составе группы загрузок. Этот флаг ЗАПРЕЩЕНО изменять.
FLGSGROUPMASTR
Указание что это структура - мастер группы. Этот флаг ЗАПРЕЩЕНО изменять.
Она не является загрузкой, но представляет отдельный уровень общих данных для всех членов группы, все загрузки из этой группы будут брать значения полей UserAgent, Headers и cookies, если у них эти поля оставлены путстыми.

Быстрая справка

ОС C поддержкой WinAPI v4
DLL 2fap.exe
Библиотека -
Заголовок comthrd-plugin.h

Смотри также

Функционал диалога добавления и свойств загрузки