Gros fichiers

Envoyer des fichiers volumineux sans les charger en mémoire, et suivre la progression de l'envoi.

Prérequis

Un envoi avec pièces jointes qui fonctionne : voir Pièces jointes.

Depuis le disque, pas depuis la mémoire

Façon	Comportement	Usage
`FilesPath` (chemins des fichiers)	Le SDK lit chaque fichier par morceaux de 512 Kio : le fichier n'est jamais chargé en entier.	Gros fichiers.
`filesList` (contenu en mémoire)	Le fichier est déjà entier en mémoire avant l'envoi.	Petits fichiers produits par votre application.

Pour un gros fichier, passez toujours son chemin.

Suivre la progression

var fileHelper = new FileHelper();
var morceaux = new ConcurrentDictionary<long, bool>();   // morceaux du fichier en cours

fileHelper.UploadFileStart_Event += (nom, taille) => morceaux.Clear();
fileHelper.UploadChunkCompleted_Event += (nom, taille, index, total) =>
{
    // Appelé depuis plusieurs fils, dans le désordre, parfois deux fois pour un même morceau.
    morceaux.TryAdd(index, true);
    AfficherProgression((int)Math.Min(100, morceaux.Count * 100L / total));
};
fileHelper.UploadFileEnd_Event += (nom, taille) => AfficherProgression(100);

var args = new MutliRecipientArgs(
    endPointUri: endpoint, serial: serial, user: apiUser, psw: apiPassword,
    recipients: recipients, message: message, subject: subject,
    password: null, filesList: null,
    sendMode: SendMethodEnum.onlyEmail, getBackHtml: false,
    showSubject: true, getNotify: true, cultureID: "fr-CA",
    maximumOpenTime: 5, minutesExpiration: 10080)
{
    FilesPath = new List<string> { cheminFichier },
};

// Passez votre FileHelper : sans lui, le SDK crée le sien et vos événements ne se déclenchent pas.
var response = MessageHelper.MultiRecipientMessage(args, fileHelper);

import threading

from secure_exchanges_sdk.helpers.file_helper import FileHelper

helper = FileHelper()
verrou = threading.Lock()
morceaux = set()  # morceaux du fichier en cours

def debut_fichier(nom, taille):
    with verrou:
        morceaux.clear()

def morceau_envoye(nom, taille, index, total):
    with verrou:  # appelé depuis plusieurs fils
        morceaux.add(index)
        afficher_progression(min(100, len(morceaux) * 100 // total))

helper.on_upload_file_start = debut_fichier
helper.on_upload_chunk_completed = morceau_envoye

answer = MessageHelper.multi_recipient_message(
    api_client=client, sems_client=sems_client,
    serial=serial, api_user=api_user, api_password=api_password,
    recipients=recipients, message=message, subject=subject,
    files_path=[chemin_fichier],
    get_back_html=False, culture_id="fr-CA",
    file_helper=helper,
)

use SecureExchanges\SDK\Helpers\FileHelper;

$envoyes = 0;
FileHelper::$onUploadFileStart = function (string $nom, int $taille) use (&$envoyes): void {
    $envoyes = 0;
};
FileHelper::$onUploadChunkCompleted = function (string $nom, int $taille, int $index, int $total) use (&$envoyes): void {
    $envoyes++;
    afficherProgression(min(100, intdiv($envoyes * 100, $total)));
};

try {
    $answer = MessageHelper::multiRecipientMessage(
        apiClient: $client, semsClient: $sems,
        serial: $serial, apiUser: $apiUser, apiPassword: $apiPassword,
        recipients: $recipients, message: $message, subject: $subject,
        filesPath: [$cheminFichier],
        getBackHtml: false, cultureId: 'fr-CA',
    );
} finally {
    // Propriétés statiques : communes à tout le processus, à remettre à null après l'envoi.
    FileHelper::$onUploadFileStart = null;
    FileHelper::$onUploadChunkCompleted = null;
}

Ne déclarez un fichier envoyé qu'à la fin de l'appel, après avoir vérifié le statut de l'envoi : un morceau peut encore échouer après que la progression a atteint 100 %.

UploadChunkCompleted_Event se déclenche aussi pour un morceau que le serveur n'a pas confirmé, puis de nouveau quand il est renvoyé : comptez les index distincts, comme dans l'exemple. Évitez UploadEvent et GetFileSizeBeforeUpload : ce sont des événements statiques, communs à tout le processus.

on_upload_progress et on_upload_finish existent dans FileHelper mais ne sont jamais appelés : utilisez les rappels de l'exemple.

$onUploadProgress et $onUploadFinish existent dans FileHelper mais ne sont jamais appelés : utilisez les rappels de l'exemple.

À savoir

Point	Détail
Taille d'un morceau	512 Kio, fixe.
Envois parallèles	.NET : `NbThreadUploads`, de 1 à 10 (6 par défaut). Python : 4 morceaux à la fois, non réglable depuis l'envoi. PHP : un morceau à la fois.
Réessais	Un morceau en échec est renvoyé, jusqu'à 10 nouvelles passes à une seconde d'intervalle. Ensuite l'envoi échoue (statut 500) et aucun message n'est envoyé.
Reprise	Aucune entre deux appels : un nouvel envoi renvoie tous les fichiers.
Délai par requête	5 minutes en .NET 8, 120 secondes en Python et en PHP ; non réglable.
Taille maximale	Le SDK n'en impose aucune : la limite de votre forfait s'applique au serveur. Voir Licence et quotas. Un fichier vide est refusé.
Empreinte	Le SDK calcule une empreinte SHA-512 de chaque fichier, vérifiée à la réception. Au-delà de 1 Go, elle est calculée par blocs : elle diffère du SHA-512 du fichier entier (`sha512sum`, par exemple).

Attention

En .NET, un chemin introuvable dans FilesPath est ignoré sans erreur : le message part sans ce fichier, avec le statut 200. Vérifiez l'existence de chaque fichier avant l'envoi.

Erreurs fréquentes

Symptôme	Cause probable	Solution
Statut 500 après une longue attente	Un morceau a échoué après tous les réessais : réseau instable ou délai dépassé	Réessayez plus tard ; sur un réseau lent, réduisez le nombre d'envois parallèles (.NET).
Statut 500 « Access denied »	Plus de 10 refus du serveur pendant l'envoi	Vérifiez vos identifiants, l'environnement et les permissions de votre licence.
.NET : les événements ne se déclenchent jamais	`FileHelper` non passé à `MessageHelper.MultiRecipientMessage`	Utilisez la surcharge `MessageHelper.MultiRecipientMessage(args, fileHelper)`.
.NET : `SettingsHelper.NbThreadUploads = 4` ne compile pas	C'est une constante (ancien guide)	Fixez `NbThreadUploads` dans les arguments de l'envoi.
« File 0 ko length error »	Fichier vide	Retirez-le de l'envoi.

Et ensuite

Télécharger les fichiers reçus
Licence et quotas : taille maximale des fichiers

Table of Contents